An AI-powered autonomous agent that investigates domains, IPs, CVEs, URLs, and emails — then delivers structured threat intelligence reports with IOC extraction, cross-investigation memory, and interactive follow-up chat.
You give CyberSentinel a target — a domain, IP address, CVE ID, suspicious URL, or raw email — and the agent autonomously:
- Remembers — searches past investigations for related targets, IOCs, or CVEs before starting
- Plans & Executes — runs a multi-step tool-calling loop (WHOIS, DNS, port scan, CVE lookup, web search, email analysis, VirusTotal)
- Reasons — the AI decides which tools to call, in what order, and how many times based on what it finds
- Reports — generates a structured Threat Intelligence Report with severity rating, findings, risk indicators, and recommended actions
- Extracts IOCs — automatically pulls out structured Indicators of Compromise (IPs, domains, CVEs, attack techniques, threat actors)
- Chats — lets you ask follow-up questions about any investigation using the full report as context
The core agentic loop uses native tool_use — not prompt chaining. The AI calls tools in any order, as many times as needed, until it has enough evidence to write a report. Supports both Google Gemini (free) and Anthropic Claude (paid).
Before every investigation, CyberSentinel searches your past history for related findings — matching by domain, IP overlap, CVE IDs, shared IOCs, and suspicious TLDs. Relevant context is injected into the agent's prompt so it builds on previous intelligence.
After each investigation, a separate AI call with JSON-mode output extracts 8 structured IOC categories from the full report: malicious IPs, domains, URLs, CVE IDs, suspicious emails, attack techniques, threat actors, and infrastructure notes. Results are stored in history and displayed as a color-coded grid.
After any investigation completes, a chat panel opens. Ask anything about the report — the full investigation text and IOCs are injected as context. Supports multi-turn conversation with history. Works on past investigations too (click any history entry).
┌─────────────────────────────────────────────────────────────────┐
│ BROWSER (Dark UI) │
│ Target Input → POST /api/investigate → GET /api/stream/{id} │
│ IOC Grid ← POST /api/chat → Follow-up Chat Panel │
└──────────────────────────┬──────────────────────────────────────┘
│ HTTP / SSE
┌──────────────────────────▼──────────────────────────────────────┐
│ Flask App (app.py) │
│ /api/investigate → Start background thread │
│ /api/stream/{id} → SSE event stream (real-time progress) │
│ /api/chat → Follow-up Q&A with report context │
│ /api/history → Past investigations (JSON file) │
│ /api/investigation/<id> → Full detail with raw report + IOCs │
└──────────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────┐
│ CyberSentinelAgent (agent/core.py) │
│ │
│ 1. search_memory(target) → inject related past findings │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ AGENTIC LOOP (max 10 iterations) │ │
│ │ │ │
│ │ messages → Gemini / Claude API │ │
│ │ ↓ │ │
│ │ tool_use? → execute_tool(name, input) → result │ │
│ │ ↓ │ │
│ │ append tool result → call AI again │ │
│ │ ↓ │ │
│ │ end_turn → return final report │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ 2. extract_iocs(report, steps) → structured JSON IOCs │
└──────────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────┐
│ Tools (agent/tools.py) │
│ │
│ whois_lookup → python-whois → domain age, registrar │
│ dns_lookup → dnspython → A/MX/NS/TXT/DMARC/SPF │
│ url_feature_analysis → built-in → 24 phishing features │
│ web_search → DuckDuckGo → open-source threat intel │
│ cve_lookup → NIST NVD API→ CVSS score, description │
│ port_scan → socket → 20 common ports │
│ email_header_analysis→ email lib → spoofing, phishing │
│ virustotal_lookup → VT API v3 → 70+ engine detections │
└─────────────────────────────────────────────────────────────────┘
| Layer | Technology |
|---|---|
| AI (free) | Google Gemini 2.5 Flash Lite — google-genai SDK |
| AI (paid) | Anthropic Claude claude-sonnet-4-6 — native tool_use |
| Backend | Python 3.11+, Flask 3.0 |
| Streaming | Server-Sent Events (SSE) |
| WHOIS | python-whois |
| DNS | dnspython |
| Search | DuckDuckGo Search (ddgs) |
| CVE Data | NIST NVD API v2.0 (free, no key needed) |
| Port Scan | Python socket library |
| Frontend | Vanilla HTML/CSS/JS — dark cyberpunk theme |
| Fonts | Orbitron, Share Tech Mono (Google Fonts) |
- Python 3.11+
- A free Google AI Studio key or a paid Anthropic API key
# Clone the repository
git clone https://github.com/yourusername/CyberSentinel.git
cd CyberSentinel
# Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS/Linux
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env — add your API key (see below)Edit .env:
# FREE — Google Gemini (20 req/day, no billing required)
GEMINI_API_KEY=AIzaSy...your_key_here
# OR PAID — Anthropic Claude (better quality, pay-per-use)
# ANTHROPIC_API_KEY=sk-ant-...your_key_here
# Optional — VirusTotal (free tier, skipped if absent)
# VIRUSTOTAL_API_KEY=...If both keys are set, Anthropic takes priority.
python app.pyOpen your browser at http://localhost:5000
Important: Restart the server after any .env change — API keys are loaded at startup.
- Enter a target in the investigation box:
- Domain:
suspicious-site.tk - IP:
45.33.32.156 - CVE:
CVE-2024-3094 - URL:
http://secure-paypal-login.ml/verify - Email: paste raw email text with headers
- Domain:
- The UI auto-detects the input type
- Click Investigate or press
Ctrl+Enter - Watch the real-time investigation feed
- Read the structured threat report and IOC grid
- Ask follow-up questions in the chat panel below
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/investigate |
Start investigation, returns {"id": "..."} |
GET |
/api/stream/{id} |
SSE stream of investigation progress |
POST |
/api/chat |
Follow-up chat with report context |
GET |
/api/history |
List past investigations (no raw reports) |
GET |
/api/investigation/{id} |
Full detail with raw report + IOCs |
DELETE |
/api/history |
Clear all history |
GET |
/api/health |
Provider status and configuration check |
Start an investigation:
POST /api/investigate
Content-Type: application/json
{"target": "suspicious-domain.tk"}Follow-up chat:
POST /api/chat
Content-Type: application/json
{
"investigation_id": "abc123",
"message": "What immediate actions should I take?",
"history": []
}| Field | Description |
|---|---|
| Threat Level | CRITICAL / HIGH / MEDIUM / LOW / INFORMATIONAL |
| Executive Summary | 2–3 sentence overview of key findings |
| Findings | Evidence-backed observations from all tools |
| Risk Indicators | Specific red flags with supporting data |
| Recommended Actions | Concrete, prioritized security steps |
| Confidence Level | HIGH / MEDIUM / LOW with data quality note |
| Investigation Timeline | Every tool called, with inputs and results |
| IOCs | 8 structured categories: IPs, domains, URLs, CVEs, emails, techniques, actors, infrastructure |
| Tool | Input | What It Returns |
|---|---|---|
whois_lookup |
domain | Registrar, creation date, age, country |
dns_lookup |
domain | A/AAAA/MX/NS/TXT records; SPF/DMARC presence |
url_feature_analysis |
URL | 24 phishing features, 0–100 risk score |
web_search |
query | DuckDuckGo results for threat intel |
cve_lookup |
CVE ID | CVSS score, severity, description, affected products |
port_scan |
domain/IP | Open ports, service names, high-risk flags |
email_header_analysis |
email text | Spoofing indicators, auth results, embedded URLs |
virustotal_lookup |
domain/IP/URL | Detection ratio across 70+ security engines |
CyberSentinel/
├── agent/
│ ├── core.py # Agentic loop — dual-provider (Gemini + Claude)
│ ├── memory.py # Cross-investigation memory search
│ ├── ioc_extractor.py # Structured IOC extraction via AI JSON mode
│ ├── tools.py # 8 tools: JSON schemas + Python implementations
│ ├── prompts.py # CyberSentinel system prompt
│ ├── report.py # Report text parser → structured dict
│ └── __init__.py
├── templates/
│ └── index.html # Single-page dark cyberpunk UI
├── static/
│ ├── css/style.css # Cyberpunk design system
│ └── js/app.js # SSE client, report renderer, IOC grid, chat
├── data/
│ └── history.json # Auto-generated, gitignored
├── app.py # Flask app — routes, SSE streaming, chat
├── config.py # Environment variable loader
├── requirements.txt
├── .env.example
└── .gitignore
| Target | Expected Result |
|---|---|
free-bitcoin-winner.tk |
HIGH/CRITICAL — new domain, suspicious TLD, phishing keywords |
CVE-2021-44228 |
CRITICAL — Log4Shell, CVSS 10.0, RCE |
CVE-2024-3094 |
CRITICAL — XZ Utils supply chain backdoor |
google.com |
INFORMATIONAL — established domain, clean reputation |
http://secure-paypal-login.ml/verify |
HIGH/CRITICAL — phishing URL features |
- Native tool use, not prompt chaining — tools are real JSON schemas passed to the AI; the model decides the investigation strategy
- Dual AI provider — Gemini for free access, Claude for quality; identical tool schemas work for both
- SSE streaming — progress appears in real time via
EventSource, no polling - Memory across sessions — history is persisted to JSON and scored by relevance before each new investigation
- IOC extraction is a separate AI call — uses Gemini's
response_mime_type="application/json"for reliable structured output
- Shodan API integration for advanced port/service intelligence
- AlienVault OTX threat feed lookup
- PDF export of threat reports
- Webhook support for alerting (Slack, Discord)
- Batch investigation mode for multiple targets
- Docker containerization
- STIX/TAXII threat intelligence format export
This tool is for:
- Authorized security testing of systems you own or have permission to test
- Educational purposes and learning cybersecurity concepts
- Threat intelligence research and defensive security work
Do not investigate targets without authorization.
Built as a portfolio project exploring the intersection of AI and cybersecurity.
Supports Google Gemini (free) and Anthropic Claude (paid)