Drongo integration

Drongo is a centralized security and threat intelligence platform. Connecting Suricatavel to Drongo enables:

• Automated containment: Enforce temporary IP blocks on perimeter firewalls with automatic TTL expiration.
• Threat feed synchronization: Synchronize detection rules and threat feeds curated in Drongo automatically.
• Telemetry relay: Stream alerts and network events to Drongo through an optimized, deduplicated outbox queue.
• Threat intelligence drilldown: Link directly from Suricatavel alerts into Drongo signature databases.

---

Connecting Suricatavel to Drongo

Enrollment establishes an encrypted, authenticated mutual TLS (mTLS) communication channel between Suricatavel (acting as the Root Certificate Authority) and the Drongo instance or daemon.

You can complete enrollment using any of the following methods:

Direct CLI (Recommended)

If running Drongo on the same host, container, or shared filesystem, you can issue mTLS credentials and activate pairing directly without HTTP roundtrips or tokens:

# 1. Automatically generate private key, signed certificate, and Root CA chain:
suricatavel drongo enroll --out-dir=/etc/drongo/certs

Alternatively, if Drongo already generated its own Certificate Signing Request (CSR):

# 2. Sign an existing CSR against the local Root CA:
suricatavel drongo enroll --csr=/etc/drongo/drongo.csr --cert-out=/etc/drongo/drongo.crt

drongo enroll options

• --out-dir: Destination directory to write drongo.crt, drongo.key, and ca.crt.
• --csr: Path to an external Certificate Signing Request (CSR) file.
• --cert-out: Target path to save the signed mTLS client certificate.
• --key-out: Target path to save the generated client private key.
• --ca-out: Target path to save the Root CA certificate chain.
• --validity: Certificate validity in days (default: 365).
• --force: Overwrite existing files if previously issued.

Remote CLI (API + OTP token)

If Drongo runs on a remote host or isolated network, use the Zero-trust bootstrap flow via a one-time pairing token (OTP):

1. Generate the OTP token in Suricatavel via CLI:

   suricatavel drongo token

   Returns a 64-character token valid for 15 minutes.

2. Generate private key and CSR on the Drongo node: On the host running Drongo (private keys should never leave the client node):

   openssl req -new -newkey rsa:4096 -nodes \
     -keyout /etc/drongo/drongo.key \
     -out /etc/drongo/drongo.csr \
     -subj "/CN=drongo.internal/O=Suricatavel"

3. Submit enrollment request to Suricatavel:

   curl -s -X POST https://<suricatavel-host>/api/v1/drongo/pki/enroll \
     -H "Content-Type: application/json" \
     -d "{
       \"pairing_token\": \"<TOKEN>\",
       \"csr\": \"$(awk '{printf \"%s\\n\", $0}' /etc/drongo/drongo.csr)\"
     }" > /tmp/drongo_creds.json

4. Extract the issued certificate and CA chain:

   jq -r .certificate /tmp/drongo_creds.json > /etc/drongo/drongo.crt
   jq -r .ca_chain /tmp/drongo_creds.json > /etc/drongo/ca.crt

Web UI

You can also trigger pairing from the web interface:

1. In Suricatavel, navigate to Settings > Drongo.
2. Click Generate pairing token. Copy the one-time token.
3. Configure your Drongo node with the Suricatavel URL and the token to submit its CSR.
4. Upon successful exchange, the pairing status updates to Paired.

Tip

Once enrolled, monitor connection health, rotate credentials, or tune forwarding settings anytime with suricatavel drongo status or in Settings > Drongo.

---

Telemetry relay

Configure which telemetry Suricatavel streams to Drongo:

• Forward alerts: Streams high-priority security alerts with enriched threat metadata.
• Forward events: Streams raw network telemetry (DNS, HTTP, TLS, flow events).
• Outbox buffering: Telemetry is buffered locally in an outbox table and dispatched asynchronously via HTTP or Kafka to guarantee delivery during network interruptions.

Note

Capture loop prevention: Suricatavel automatically injects a BPF exclusion filter into Suricata sensors (host <drongo-ip> and port <port>) to prevent sensors from capturing their own reporting traffic to Drongo.

---

Automated containment

When Drongo detects malicious activity across your fleet, it dispatches an inbound containment request to Suricatavel.

How containment works

1. Drongo sends an enforcement request specifying the target IP address and a TTL (Time to live) in seconds.
2. Suricatavel validates the request against local safeguards:
   • IP whitelist: Critical infrastructure IPs configured in your whitelist are never blocked.
   • Input sanitization: Values are strictly validated to prevent command injection on firewall adapters.
3. Suricatavel applies the temporary block on your perimeter firewalls (pfSense, OPNsense, OpenWrt, MikroTik, or Linux nftables).
4. When the TTL expires, the block is automatically removed.
5. If Drongo revokes the containment early, a rollback request removes the rule immediately.

All containment actions are recorded and visible under Firewalls > History.

---

Threat feed synchronization

Suricatavel periodically queries Drongo for updated rule feeds. When Drongo publishes new signatures or IOC datasets, Suricatavel fetches and stages them for deployment to your sensors.

You can also trigger an immediate push sync from Drongo, which notifies Suricatavel to refresh its active feeds immediately.

---

CLI operational commands

Suricatavel provides a complete command group to inspect, test, and manage the Drongo integration without a browser:

# Display integration status, mTLS credentials, and outbox queue metrics
suricatavel drongo status

# Verify reachability and credentials against HTTP endpoints or Kafka brokers
suricatavel drongo test

# Drain pending telemetry records from the outbox queue
suricatavel drongo dispatch --limit=100 --max-attempts=5 --time-budget=50

# Trigger immediate behavioral rules synchronization and deployment to sensors
suricatavel drongo sync-feed

# Generate a one-time enrollment pairing token for remote nodes (15 min validity)
suricatavel drongo token

# Directly enroll the Drongo node and issue local mTLS credentials
suricatavel drongo enroll --out-dir=/etc/drongo/certs

Tip

To inspect interactive help, options, and syntax examples directly in the terminal, run suricatavel drongo help.