See llms.txt for all machine-readable content.

Back to Templates

Score DNS threats with VirusTotal, Abuse.ch, HashiCorp Vault and Gemini

Created by

Created by: Lukasz FD || lukaszfd
Lukasz FD

Last update

Last update 5 days ago

Categories

Share

Quick overview

Turns DNS traffic into threat verdicts. Each new domain/IP pair is checked with VirusTotal, ThreatFox and URLhaus, scored by deterministic rules in PostgreSQL, reviewed by a Gemini AI agent with pgvector memory, then stored, emailed and optionally blocked in Pi-hole. All secrets come from HashiCorp Vault.

How it works

  1. Every 3 minutes the workflow loads its configuration from PostgreSQL (thresholds, the active AI prompt and the 1–5 threat scale) and picks one pending observable: a domain and the IP it resolved to.
  2. VirusTotal checks the IP. If detections are below the configured gate, the observable is stored as clean without further API calls or AI tokens. A failed lookup is never stored as clean; the observable stays in the queue.
  3. Above the gate, ThreatFox (by IP) and URLhaus (by domain) add context such as malware families and online malicious URLs.
  4. A PostgreSQL function computes a deterministic 1–5 rule score with a step-by-step trace, including a cap for trusted infrastructure (Google, Microsoft, Cloudflare…).
  5. A Gemini AI agent reviews the evidence and the rule score. Its tool searches earlier verdicts in pgvector. It returns structured JSON with a label, an English summary and a Polish analysis, and may move the score only within a configured limit; the workflow enforces that limit and falls back to the rule score if the agent fails.
  6. Raw CTI responses, the verdict and an audit record are written to PostgreSQL, and the verdict is embedded into vector memory.
  7. A severity-coloured email is sent when the score reaches the alert threshold. Domains with enough VirusTotal detections that are not trusted infrastructure are added to the Pi-hole denylist, and every block attempt is logged.

Setup

  1. Run PostgreSQL 16 with the pgvector extension and apply the schema from the Cyber Sentinel repository (config/postgres): the cyber_sentinel schema for DNS data and verdicts, and cyber_sentinel_ai for settings, prompts, allow-lists, audit and vector memory.
  2. Feed DNS queries into cyber_sentinel.dns_queries. The project uses Pi-hole, a passive dnsmasq logger and a small Python log processor; any source that fills the table works.
  3. Install the community node n8n-nodes-hashi-vault and create a read-only Vault token. Store the secrets under cyber-sentinel/: VirusTotal and Abuse.ch API keys, the Gemini API key, PostgreSQL credentials, the SMTP login with an alert recipient field (to) and, optionally, a Pi-hole application password.
  4. Create the n8n credentials: HashiCorp Vault, Postgres, Google Gemini and SMTP. Point every node with a credential to them.
  5. Set the Pi-hole API address in the Pi-hole nodes, or set pihole_block_enabled to 0 in cyber_sentinel_ai.ai_settings to disable automatic blocking.
  6. Activate the workflow. Thresholds and the prompt are changed in the database, not in the workflow.

Requirements

  • n8n with the community node n8n-nodes-hashi-vault
  • HashiCorp Vault (KV v2)
  • PostgreSQL 16 with pgvector (pg_cron optional, for partition retention)
  • VirusTotal API key (free tier is enough: one observable per run)
  • Abuse.ch Auth-Key (ThreatFox and URLhaus)
  • Google Gemini API key
  • SMTP account for alerts
  • Pi-hole v6 (optional, for automatic blocking)

Customization

  • Change thresholds (VirusTotal gate, score limits, AI deviation, email and block thresholds) in cyber_sentinel_ai.ai_settings — no workflow edit needed.
  • Add a new version of the AI prompt in cyber_sentinel_ai.prompt_templates and activate it.
  • Extend trusted infrastructure and the allow-list (Tranco top domains plus manual entries, with exclusions for user-content platforms).
  • Swap the Gemini model in the Chat Model node; the Embeddings model must stay the same or vector memory has to be rebuilt.
  • Replace the email node with Slack, Teams or a webhook.

Additional info

Part of Cyber Sentinel, an open-source home SOC running on a Raspberry Pi 5, deployed end to end with Ansible.

Repository: https://github.com/lukaszFD/cyber-sentinel
Documentation: https://lukaszfd.github.io/cyber-sentinel/
Release v2.0.0: https://github.com/lukaszFD/cyber-sentinel/releases/tag/v2.0.0