Skip to main content

Autonomous AI SecurityAgent & Vector Memory

At the core of VulnerGuard's scanning pipeline is SecurityAgent, an autonomous state-machine orchestrator that combines multi-provider LLM reasoning with semantic vector similarity search to plan, execute, correlate, and summarize multi-engine security assessments.

1. End-to-End Agent Lifecycle​

When POST /api/scan triggers an assessment, SecurityAgent executes five coordinated stages:

┌──────────────┐     ┌──────────────────┐     ┌─────────────────────┐     ┌─────────────────────────┐
│ Operator UI  │     │  Core API Plane  │     │ SecurityAgent       │     │ MCP Execution Plane     │
│ (Socket.IO)  │     │  (/api/scan)     │     │ + Vector + AI Model │     │ + 14 Isolated Workers   │
└──────┬───────┘     └────────┬─────────┘     └──────────┬──────────┘     └────────────┬────────────┘
       │                      │                          │                             │
       │ 1. POST /api/scan    │                          │                             │
       ├─────────────────────►│                          │                             │
       │                      │ 2. Create Scan Row       │                             │
       │                      │    + Spawn Agent Thread  │                             │
       │                      ├─────────────────────────►│                             │
       │ 3. emit('join', id)  │                          │                             │
       ├─────────────────────►│                          │                             │
       │ 4. Replay log_buffer │                          │                             │
       │◄─────────────────────┤                          │                             │
       │                      │                          │ 5. Vector Memory Recall     │
       │                      │                          │    + AI Tool Sequencing     │
       │                      │                          ├──────────────┐              │
       │                      │                          │◄─────────────┘              │
       │                      │                          │ 6. Dispatch Worker Sandbox  │
       │                      │                          ├────────────────────────────►│
       │                      │                          │ 7. Return Structured Output │
       │                      │                          │◄────────────────────────────┤
       │                      │                          │ 8. Parse + Store Vectors    │
       │ 9. Live scan_update + scan_progress             │    + Executive AI Brief     │
       │◄────────────────────────────────────────────────┤                             │
       │ 10. Emit scan_completed (Full Report)           │                             │
       │◄────────────────────────────────────────────────┤                             │

2. Vector Memory Architecture​

VulnerGuard persists long-term operational memory across two dedicated vector collections initialized by VectorStore:

Collection NameVector DimensionDistance MetricStored Payload Schema
security_findings384Cosinescan_id, tool, type, severity, description, details, timestamp
scan_history384Cosinescan_id, target, tools, findings_count, summary, timestamp

How Vector Recall Improves Every Subsequent Scan​

Before executing a single packet against a target, SecurityAgent.retrieve_planning_context() queries the vector store for semantically similar targets and historical findings:

  • If a target domain previously exhibited specific misconfigurations, CMS endpoints, or TLS cipher weaknesses, those prior vectors are injected into the planning context so the agent prioritizes relevant verification templates.

3. Dual-Mode Tool Dispatch: Structured Artifacts & Live Streaming​

Different security tools produce fundamentally different output structures. VulnerGuard's SecurityAgent uses a dual-mode execution strategy to guarantee zero data loss:

  1. Structured Artifact Engines (nuclei, subfinder, ffuf, katana, testssl, gitleaks, wpscan, trivy):
    • Dispatched via the MCP Execution Plane with a deterministic output path inside the isolated artifact store.
    • Built-in failover ensures that even under heavy concurrency, structured JSON/XML artifacts are reliably captured and parsed into normalized Vulnerability records.
  2. Line-Oriented Streaming Engines (nmap, sqlmap, zap):
    • Stream real-time stdout chunks over the execution bus while simultaneously writing XML/JSON reports to the artifact store.

4. Human-in-the-Loop Approval Gates​

To prevent accidental disruption during production assessments, SecurityAgent classifies tools by intrusiveness and enforces configurable approval gates controlled via Admin Vault policies:

  • AGENT_AUTO_APPROVE_LOW_RISK=true: Passive and standard discovery/scanning engines (nmap, subfinder, katana, ffuf, testssl, nuclei, zap, wpscan, gitleaks, trivy) execute immediately without blocking.
  • AGENT_REQUIRE_APPROVAL_HIGH_RISK=true: Active exploitation frameworks (metasploit, beef, set) pause the agent step and emit an approval_required event to the operator UI. Operators can approve or skip the step via POST /api/scan/<scan_id>/approve.

5. Executive AI Analysis​

Once all tool steps conclude, SecurityAgent.analyze_results() compiles all discovered vulnerabilities and invokes the configured LLM provider:

  • Primary Reasoning Engine: Anthropic Claude (claude-sonnet-4-5) via ANTHROPIC_API_KEY.
  • OpenAI-Compatible / Red-Team Provider: Venice AI or OpenAI-compatible endpoints via LLM_BASE_URL and OPENAI_API_KEY.
  • Generated Deliverables:
    • Executive Risk Posture Summary (summary.ai_analysis)
    • Severity Distribution Breakdown (critical, high, medium, low, info)
    • Actionable remediation guidance (WAF rules, HTTP security headers, TLS cipher suites, and secret rotation steps).