Kestrel-SGR (APCS) — Autonomous Phishing Control System

APCS is a deterministic, multi‑plane security control system that detects, analyzes, predicts, and actively neutralises social‑engineering threats (phishing, smishing, vishing) across enterprise environments.

Built on a Skill Graph Runtime (SGR) — a Directed Acyclic Graph (DAG) executor that chains perception, decision, and dominance skills with schema validation, confidence aggregation, and saga-based rollback.

Watch the Kestrel-SGR demo on YouTube

Features

• Skill Graph Runtime — 26-node DAG executor with JSON schema validation, confidence aggregation, and Celery-backed execution
• IP & File Reputation — VirusTotal, AbuseIPDB, AlienVault OTX lookups for IP addresses and SHA-256 file hashes
• Threat Intelligence — URL/domain IoC matching via OTX pulses and VirusTotal
• OWASP Security Analysis — 10 automated detectors covering OWASP Top 10 patterns (XSS, SQLi, SSRF, open redirect, …)
• Phishing Validation — brand-impersonation detection, SSL checks, and header-anomaly analysis
• Customer Report Portal — phishing report submission with optional auto-remediation and history
• Email Security Integrations — Microsoft Defender for Email and Cisco ESA adapters (quarantine, block sender, verdicts)
• URL Detonation Engine — Multi-link reputation analysis via CyberWatch API + local heuristics (malicious/suspicious/safe classification)
• File Upload Scanning — Upload .eml, .txt, .msg, .html files for automatic pipeline analysis
• Multi-Signal Risk Scoring — 20+ signals including detonation, SPF/DKIM/DMARC spoof flags, ML risk score, OWASP, IP/file reputation, and threat-intel IoCs
• Veto Overrides — Hard deny on spoofed emails, malicious detonations, malicious reputation, phishing likelihood, or high ML risk
• Lightweight Rego Policy Engine — Python-based OPA evaluator with runtime policy updates
• ML Scorer — scikit-learn based risk estimation (displayed as ML Confidence)
• Real-Time Dashboard — Glassmorphic UI with D3.js DAG visualization, SSE live updates, replay, and analytics
• Forensic Replay — Encrypted trace store with step-by-step skill replay
• SOAR Playbooks — Action buttons to execute remediation (block, quarantine, MFA reset)
• PII Redaction — Automatic detection and redaction of PII before external processing
• RBAC — Token-based auth with Analyst and Admin roles
• Transaction Saga — Automatic rollback of side-effects on failure
• 506 passing tests — 97.34% overall line coverage, ≥99% across all core and skills modules

Quick Start

# Install from PyPI
pip install kestrel-sgr
kestrel-sgr

# Or run the published Docker image (built & pushed to GHCR by CI):
# docker run -p 9090:9090 ghcr.io/rohit-barui/kestrel-sgr:latest

# Or one-click install (creates venv, installs deps, starts server):
.\Kestrel-sgr.ps1

Open http://localhost:9090 and enter the default Analyst token:

fe12751c01c2ad2a4f99004855697e18c173cfe54fdf57436b29f2a2923946b5

How It Works — Flow Diagram

flowchart TB
    subgraph Ingest["1 · Ingestion"]
        I[POST /api/scan] --> ING[ingest_payload]
        I2[POST /api/scan/upload] --> ING
        I3[POST /api/report/phishing] --> ING
    end

    subgraph Perception["2 · Perception Plane (14 nodes)"]
        ING --> EU[extract_urls]
        ING --> SQ[scan_qr_codes]
        ING --> AP[extract_archive_password]
        ING --> EE[extract_entities]
        ING --> VSD[validate_spf_dkim]
        EU --> WL[whois_lookup]
        EU --> ED[enrich_dns]
        EU --> DTS[detect_typo_squatting]
        EU --> EX[enrich_external]
        EU --> DU[detonate_urls]
        EU --> CIP[check_ip_reputation]
        ING --> CFR[check_file_reputation]
        EU --> TIL[threat_intel_lookup]
        EU --> OW[owasp_analysis]
        ING --> PV[phishing_validation]
        VSD --> PV
        EU --> PV
    end

    subgraph Decision["3 · Decision Plane"]
        EU --> MLS[ml_score]
        SQ --> MLS
        AP --> MLS
        WL --> MLS
        ED --> MLS
        DTS --> MLS
        EE --> MLS
        EX --> MLS
        DU --> MLS
        VSD --> MLS
        CIP --> MLS
        CFR --> MLS
        TIL --> MLS
        OW --> MLS
        PV --> MLS
        EU --> AR[aggregate_risk]
        SQ --> AR
        AP --> AR
        WL --> AR
        ED --> AR
        DTS --> AR
        DU --> AR
        CIP --> AR
        CFR --> AR
        TIL --> AR
        OW --> AR
        PV --> AR
        MLS --> AR
        AR --> AV[apply_veto]
        AV --> RA[recommend_actions]
        AV --> POL[Rego Policy]
        POL --> AV
    end

    subgraph Dominance["4 · Dominance Plane"]
        RA --> DHC[deploy_honey_credentials]
        RA --> RL[rewrite_links]
        RA --> CA[containment_actions]
        RA --> BI[block_ip]
        RA --> QE[quarantine_email]
        RA --> MR[trigger_mfa_reset]
    end

    subgraph Output["5 · Response & Audit"]
        AV --> RES[scan response + decision]
        RA --> SSE[SSE live updates]
        AV --> REP[encrypted forensic replay]
        AV --> NC[notifications / SIEM]
    end

Architecture

┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
│   Perception Plane  │   │   Decision Plane    │   │   Dominance Plane   │
│  (Ingestion, parse, │   │ (Risk scoring,      │   │ (Deception,         │
│   enrichment,       │   │  policy evaluation) │   │  containment)       │
│   reputation, OWASP)│   └───────┬─────────────┘   └───────┬─────────────┘
└───────┬─────────────┘           │                         │
        │                         ▼                         ▼
        └───────► SGR ◄───┌────────────────┐   ┌──────────────────────────┐
                         │ Core Package   │   │ Integrations              │
                         │ engine, policy,│   │ VT · AbuseIPDB · OTX ·    │
                         │ gateway, replay│   │ Defender · Cisco ESA      │
                         └────────────────┘   └──────────────────────────┘

Planes

1. Perception — Ingests raw payloads, extracts URLs/QR codes/passwords, enriches with WHOIS/DNS, detects typo-squatting, extracts entities, detonates URLs, checks IP/file reputation, runs OWASP analysis, and validates phishing signals
2. Decision — Aggregates risk from 20+ signals, applies veto overrides and Rego policy, recommends actions, validates SPF/DKIM/DMARC
3. Dominance — Deploys honey credentials, rewrites links, blocks IPs, quarantines emails, triggers MFA resets, and remediates via Defender/Cisco ESA

API Endpoints

Repository Structure

Kestrel-SGR/
├── server.py                 # REST API + static router
├── core/                     # Core runtime (engine, policy, gateway, detonation, integrations, etc.)
├── skills/                   # DAG skill nodes (perception, decision, dominance, reputation, owasp)
├── policies/                 # Rego policy files
├── web/                      # Dashboard frontend (HTML/JS/CSS)
├── tests/                    # 506 unit & integration tests
├── docs/                     # Documentation
├── docker/                   # Docker + load-test config
├── ci/                       # Coverage gate script
├── Kestrel-sgr.ps1           # One-click installer
└── requirements.txt

Documentation

Coming Soon (v0.6.0)

• ML Model Retraining — Extend feature extractor with v0.5 signals (IP/file reputation, OWASP risk, threat-intel IoC matches, phishing validation) and retrain the RandomForest risk scorer
• Integration Health Probes — Per-provider connectivity checks (VirusTotal, AbuseIPDB, OTX, Defender, Cisco ESA) via /api/integrations/health with dashboard readiness status
• Phishing Report Automation — Persistent report store with report_id, status tracking, and automatic Defender/Cisco ESA remediation dispatch on auto_remediate=true
• Docker/K8s Deployment Docs — Compose files, Helm chart, and vault-backed secret injection guides for new integration credentials
• GitHub Project Board — Sprint planning board (manual setup required; gh token lacks project scope)

License

GNU Affero General Public License v3.0 — see LICENSE for details.

Owner

Rohit Barui — GitHub