forth-ics-inspire/artemis

1. What this repo is

ARTEMIS is a modular BGP hijack detection and mitigation system built as a multi-container application. The repository is split into service-specific Python components, deployment manifests, and test/demonstration environments.

2. Top-level architectural shape

The system is organized around three planes:

- Monitoring/ingestion: collectors that consume BGP updates from live feeds, historical feeds, or local routers.

- Detection/decision: services that compare updates against configured prefixes, origin ASes, and routing rules.

- Control/UI/mitigation: services that expose configuration, persist state, notify operators, and optionally trigger mitigation actions.

3. Ingress sources

The monitoring layer includes separate tap services for different sources:

- bgpstreamlivetap, bgpstreamhisttap, bgpstreamkafkatap for CAIDA/BGPStream live, historical, and Kafka-based inputs.

- riperistap for RIPE RIS live data.

- exabgptap for local ExaBGP feeds.

- fileobserver for file-based update observation.

These are the main external data entry points into the system.

4. Detection core

The main decision logic lives in backend-services/detection, backed by a prefixtree service for fast prefix/rule matching. Detection consumes incoming BGP events, checks them against the configured “ground truth” and ARTEMIS rules, and classifies hijack-related conditions such as exact-prefix, sub-prefix, squatting, and policy violations.

5. Configuration and startup control

backend-services/configuration is the control plane for loading, validating, and serving ARTEMIS configuration. autostarter orchestrates service startup, while autoignore handles automatic suppression/ignoring of events under certain conditions. These services form the “operational policy” boundary of the system.

6. Persistence and backend data model

The backend-services/database component owns the persistent store and schema lifecycle. It includes SQL migrations, initialization metadata, and Hasura metadata files, indicating that the database is a central system-of-record for configuration, alerts, and operational state. The chart also includes postgres, mongodb, redis, rabbitmq, pg-amqp-bridge, and postgrest, showing that persistence is split between relational state, queueing, and auxiliary datastores.

7. Messaging and async coordination

ARTEMIS relies on asynchronous service-to-service communication rather than a single monolith. RabbitMQ is the primary queueing backbone, with Redis used for coordination/cache-like runtime state. The presence of a pg-amqp-bridge deployment suggests database events are bridged into the message bus so downstream services can react without tight coupling.

8. Notifications and mitigation

backend-services/notifier emits operator-facing alerts, while backend-services/mitigation is the action boundary for active response. The README notes mitigation is supported but still limited in scope compared with detection, so this is a distinct subsystem rather than the core path.

9. Visualization and API layer

The repository includes frontend, graphql, and Hasura-related deployment artifacts, which together form the user-facing and API-access layer. The UI is used to inspect events, edit configuration, and control modules. The API boundary is important: operator actions enter through the UI/API layer and then flow to configuration, database, and control services.

10. Deployment model

The system is designed to run either with docker-compose for single-host use or on Kubernetes via artemis-chart. The Helm chart packages each microservice as its own deployment, with shared services and config maps for runtime configuration. That makes the deployment topology a key architectural concern: services are independently scaled and can be selectively enabled.

11. Operational configuration and runtime assets

The repo contains shared config templates for logging, Redis, Nginx, ExaBGP, SQL schema/init scripts, and service-specific environment files. This indicates a configuration-heavy architecture where behavior is shaped by mounted files and container startup scripts rather than hardcoded defaults.

12. Testing and validation boundaries

There are dedicated integration-style test harnesses under testing/ for detection, autoignore, autoconf, and RPKI scenarios, plus entrypoint tests for service startup contracts. These tests mirror the service boundaries, which is useful when drawing the architecture: the repo is structured around independently verifiable microservices.

13. External dependencies that materially shape the architecture

The main external technologies are BGPStream/RIPE RIS/ExaBGP for telemetry, PostgreSQL/Hasura for persistent state and API exposure, RabbitMQ/Redis for runtime coordination, and Kubernetes/Docker for deployment. Grafana dashboards are included for monitoring the system itself and the detected events.

14. Overall data flow to diagram

A practical diagram should show: BGP feeds enter the tap services; those feed detection and prefix-matching logic; detection reads configuration/state from the database-backed control plane; alerts and events are published through the async bus; notifier/UI consume the resulting state; mitigation can send outbound routing actions back through ExaBGP or other configured control paths.