How benitamags/autoforensics-ai works
Purpose and Entry Points
AutoForensics AI is a Python multi-agent incident-analysis pipeline for PCAPs and security logs. It extracts IOCs, filters them before costly enrichment, detects attacks, maps vulnerabilities/MITRE techniques, reconstructs timelines, and produces remediation and HTML dashboard outputs.
Primary entry points are the coordinator at agents/orchestrator/agent.py, individual deployable ADK agents under agents/*/agent.py, and deployment automation in deploy/deploy_all.sh.
Orchestration and Agent Boundary
The orchestrator accepts a natural-language analysis request containing file paths and coordinates remote specialists over the A2A protocol. Its remote-agent configuration is expected to be maintained after deployment. It is the control-plane boundary between the user/Vertex Agent Engine request and independently deployed analysis services.
Grounding: agents/orchestrator/agent.py, agents/orchestrator/plugins/memory_plugin.py, agents/orchestrator/.agent_engine_config.json.
Ingestion and IOC Extraction
Two source-specific workers convert raw evidence into structured security observations:
• PCAP parsing processes network traffic using Scapy and extracts network IOCs.
• Log parsing extracts security events and IOCs from log files.
These agents isolate format- and file-processing concerns from downstream reasoning, so later stages consume normalized shared models rather than raw captures/logs.
Grounding: agents/pcap_parser/agent.py, agents/log_parser/agent.py, shared/data_models.py.
IOC Gating and Enrichment
IOC gating is the cost and rate-control stage: it scores/filter candidates before external reputation lookups, targeting roughly 80%+ reduction in unnecessary API calls. Only gated IOCs proceed to enrichment, establishing a deliberate boundary between local evidence processing and quota-bound third-party services.
Threat intelligence enriches approved indicators using configured services such as VirusTotal, AbuseIPDB, and optionally Shodan.
Grounding: agents/ioc_gating/agent.py, agents/threat_intel/agent.py, shared/constants.py.
Detection and Investigation Synthesis
Attack detection applies Gemini-powered reasoning to classify activity and map observed behavior to MITRE ATT&CK. Vulnerability analysis associates evidence with CVEs or vulnerability context. Timeline construction joins parsed events, detections, and enrichment into attack-phase chronology.
These stages consume prior results rather than directly owning raw-file ingestion or external enrichment policy.
Grounding: agents/attack_detection/agent.py, agents/vulnerability_analysis/agent.py, agents/timeline_builder/agent.py.
Response and Reporting
Remediation converts findings into prioritized P0/P1/P2 response recommendations. Dashboard generation renders the consolidated investigation into an interactive HTML-oriented report. The orchestrator returns the assembled analysis to the caller, while Agent Engine memory can retain longer-lived context.
Grounding: agents/remediation/agent.py, agents/dashboard_generator/agent.py, agents/orchestrator/plugins/memory_plugin.py.
Shared Contracts, Runtime, and Operations
shared/data_models.py, shared/constants.py, and shared/utils.py form the internal contract/utilities layer intended to keep agent payloads and conventions consistent. Runtime is Python 3.9+ with Google ADK and Gemini 2.0, deployed on Vertex AI Agent Engine; Cloud Storage and Cloud Logging are required Google Cloud integrations. Per-agent .agent_engine_config.json and requirements.txt support independent packaging/deployment.
Operational automation deploys, discovers/updates remote URLs, tests, and cleans up the Agent Engine fleet.
Grounding: shared/data_models.py, deploy/deploy_all.sh, deploy/update_agent_urls.py.
Main entry points: orchestrator/agent.py Orchestrator · data_models.py Shared Data Models · threat_intel/agent.py Threat Intelligence · timeline_builder/agent.py Timeline Builder
Components 19
Control Plane
Coordinates independently deployed analysis agents.
- Caller / Agent Engine
- Orchestrator · Dispatches analysis requests to remote specialists over A2A.
agents/orchestrator/agent.py - Agent Memory · Retains longer-lived investigation context.
agents/orchestrator/plugins/memory_plugin.py - Remote Agent Config · Stores deployed specialist endpoints.
agents/orchestrator/.agent_engine_config.json
Evidence Processing
Converts raw evidence into normalized observations.
- PCAP Parser · Parses network captures and extracts network IOCs.
agents/pcap_parser/agent.py - Log Parser · Extracts security events and IOCs from logs.
agents/log_parser/agent.py
Investigation Pipeline
Filters, enriches, detects, and synthesizes findings.
- IOC Gating · Scores and filters indicators before paid or rate-limited lookups.
agents/ioc_gating/agent.py - Threat Intelligence · Enriches approved indicators with reputation services.
agents/threat_intel/agent.py - Reputation Services · VirusTotal, AbuseIPDB, and optional Shodan.
- Attack Detection · Uses Gemini reasoning to classify activity and map MITRE ATT&CK.
agents/attack_detection/agent.py - Vulnerability Analysis · Associates evidence with CVE and vulnerability context.
agents/vulnerability_analysis/agent.py - Timeline Builder · Builds attack-phase chronology from investigation results.
agents/timeline_builder/agent.py - Remediation · Prioritizes P0/P1/P2 response recommendations.
agents/remediation/agent.py - Dashboard Generator · Renders the consolidated investigation as an HTML report.
agents/dashboard_generator/agent.py
Shared Runtime & Operations
Contracts, cloud runtime, and fleet automation.
- Shared Data Models · Normalizes payloads exchanged by agents.
shared/data_models.py - Shared Constants · Provides shared conventions and enrichment configuration.
shared/constants.py - Vertex Agent Engine · Hosts independently deployed ADK agents.
- Deployment Automation · Deploys, discovers, tests, updates, and cleans up the agent fleet.
deploy/deploy_all.sh - Remote URL Updater · Updates orchestrator remote-agent endpoints after deployment.
deploy/update_agent_urls.py
Connections 22
- Caller / Agent Engine → Orchestrator: analysis request
- Orchestrator → Agent Memory: context
- Orchestrator → Remote Agent Config: reads endpoints
- Orchestrator → PCAP Parser: A2A dispatch
- Orchestrator → Log Parser: A2A dispatch
- PCAP Parser → Shared Data Models: normalized observations
- Log Parser → Shared Data Models: events and IOCs
- Shared Data Models → IOC Gating: IOC candidates
- IOC Gating → Threat Intelligence: approved IOCs
- Threat Intelligence → Reputation Services: reputation lookups
- Shared Constants → Threat Intelligence: service configuration
- Shared Data Models → Attack Detection: evidence
- Shared Data Models → Vulnerability Analysis: evidence
- Threat Intelligence → Timeline Builder: enrichment
- Attack Detection → Timeline Builder: detections
- Timeline Builder → Remediation: investigation findings
- Timeline Builder → Dashboard Generator: consolidated investigation
- Remediation → Dashboard Generator: prioritized actions
- Dashboard Generator → Orchestrator: report output
- Deployment Automation → Vertex Agent Engine: deploys fleet
- Remote URL Updater → Remote Agent Config: updates URLs
- Vertex Agent Engine → Orchestrator: hosts