# benitamags/autoforensics-ai architecture

> Architecture diagram of the GitHub repository benitamags/autoforensics-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benitamags/autoforensics-ai
- Repository: https://github.com/benitamags/autoforensics-ai

## Overview

#### 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: [`agents/orchestrator/agent.py`](https://github.com/benitamags/autoforensics-ai/blob/main/agents/orchestrator/agent.py) (Orchestrator), [`shared/data_models.py`](https://github.com/benitamags/autoforensics-ai/blob/main/shared/data_models.py) (Shared Data Models), [`agents/threat_intel/agent.py`](https://github.com/benitamags/autoforensics-ai/blob/main/agents/threat_intel/agent.py) (Threat Intelligence), [`agents/timeline_builder/agent.py`](https://github.com/benitamags/autoforensics-ai/blob/main/agents/timeline_builder/agent.py) (Timeline Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_caller(("Caller / Agent Engine<br/>request source"))
  node_orchestrator{{"Orchestrator<br/>ADK coordinator<br/>[agent.py]"}}
  node_memory["Agent Memory<br/>memory plugin<br/>[memory_plugin.py]"]
  node_remote_config["Remote Agent Config<br/>Agent Engine config"]
end

subgraph group_evidence["Evidence Processing"]
  node_pcap["PCAP Parser<br/>ADK agent<br/>[agent.py]"]
  node_logs["Log Parser<br/>ADK agent<br/>[agent.py]"]
end

subgraph group_analysis["Investigation Pipeline"]
  node_gating["IOC Gating<br/>ADK agent<br/>[agent.py]"]
  node_intel["Threat Intelligence<br/>ADK agent<br/>[agent.py]"]
  node_external_ti{{"Reputation Services<br/>external APIs"}}
  node_detection["Attack Detection<br/>ADK agent<br/>[agent.py]"]
  node_vulns["Vulnerability Analysis<br/>ADK agent<br/>[agent.py]"]
  node_timeline["Timeline Builder<br/>ADK agent<br/>[agent.py]"]
  node_remediation["Remediation<br/>ADK agent<br/>[agent.py]"]
  node_dashboard["Dashboard Generator<br/>ADK agent<br/>[agent.py]"]
end

subgraph group_platform["Shared Runtime &amp; Operations"]
  node_models["Shared Data Models<br/>contract layer<br/>[data_models.py]"]
  node_constants["Shared Constants<br/>policy/config layer<br/>[constants.py]"]
  node_agent_engine{{"Vertex Agent Engine<br/>cloud runtime"}}
  node_deploy["Deployment Automation<br/>operations script<br/>[deploy_all.sh]"]
  node_url_update["Remote URL Updater<br/>operations script"]
end

node_caller -->|"analysis request"| node_orchestrator
node_orchestrator -->|"context"| node_memory
node_orchestrator -->|"reads endpoints"| node_remote_config
node_orchestrator -->|"A2A dispatch"| node_pcap
node_orchestrator -->|"A2A dispatch"| node_logs
node_pcap -->|"normalized observations"| node_models
node_logs -->|"events and IOCs"| node_models
node_models -->|"IOC candidates"| node_gating
node_gating -->|"approved IOCs"| node_intel
node_intel -->|"reputation lookups"| node_external_ti
node_constants -.->|"service configuration"| node_intel
node_models -->|"evidence"| node_detection
node_models -->|"evidence"| node_vulns
node_intel -->|"enrichment"| node_timeline
node_detection -->|"detections"| node_timeline
node_timeline -->|"investigation findings"| node_remediation
node_timeline -->|"consolidated investigation"| node_dashboard
node_remediation -->|"prioritized actions"| node_dashboard
node_dashboard -->|"report output"| node_orchestrator
node_deploy -->|"deploys fleet"| node_agent_engine
node_url_update -->|"updates URLs"| node_remote_config
node_agent_engine -.->|"hosts"| node_orchestrator

click node_orchestrator "https://github.com/benitamags/autoforensics-ai/blob/main/agents/orchestrator/agent.py"
click node_memory "https://github.com/benitamags/autoforensics-ai/blob/main/agents/orchestrator/plugins/memory_plugin.py"
click node_remote_config "https://github.com/benitamags/autoforensics-ai/blob/main/agents/orchestrator/.agent_engine_config.json"
click node_pcap "https://github.com/benitamags/autoforensics-ai/blob/main/agents/pcap_parser/agent.py"
click node_logs "https://github.com/benitamags/autoforensics-ai/blob/main/agents/log_parser/agent.py"
click node_models "https://github.com/benitamags/autoforensics-ai/blob/main/shared/data_models.py"
click node_gating "https://github.com/benitamags/autoforensics-ai/blob/main/agents/ioc_gating/agent.py"
click node_intel "https://github.com/benitamags/autoforensics-ai/blob/main/agents/threat_intel/agent.py"
click node_detection "https://github.com/benitamags/autoforensics-ai/blob/main/agents/attack_detection/agent.py"
click node_vulns "https://github.com/benitamags/autoforensics-ai/blob/main/agents/vulnerability_analysis/agent.py"
click node_timeline "https://github.com/benitamags/autoforensics-ai/blob/main/agents/timeline_builder/agent.py"
click node_remediation "https://github.com/benitamags/autoforensics-ai/blob/main/agents/remediation/agent.py"
click node_dashboard "https://github.com/benitamags/autoforensics-ai/blob/main/agents/dashboard_generator/agent.py"
click node_constants "https://github.com/benitamags/autoforensics-ai/blob/main/shared/constants.py"
click node_deploy "https://github.com/benitamags/autoforensics-ai/blob/main/deploy/deploy_all.sh"
click node_url_update "https://github.com/benitamags/autoforensics-ai/blob/main/deploy/update_agent_urls.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_caller,node_orchestrator,node_memory,node_remote_config toneBlue
class node_pcap,node_logs toneAmber
class node_gating,node_intel,node_external_ti,node_detection,node_vulns,node_timeline,node_remediation,node_dashboard toneMint
class node_models,node_constants,node_agent_engine,node_deploy,node_url_update toneRose
```

## Components

### Control Plane

Coordinates independently deployed analysis agents.

- **Caller / Agent Engine**: request source
- [Orchestrator](https://github.com/benitamags/autoforensics-ai/blob/main/agents/orchestrator/agent.py): ADK coordinator · Dispatches analysis requests to remote specialists over A2A. · `agents/orchestrator/agent.py`
- [Agent Memory](https://github.com/benitamags/autoforensics-ai/blob/main/agents/orchestrator/plugins/memory_plugin.py): memory plugin · Retains longer-lived investigation context. · `agents/orchestrator/plugins/memory_plugin.py`
- [Remote Agent Config](https://github.com/benitamags/autoforensics-ai/blob/main/agents/orchestrator/.agent_engine_config.json): Agent Engine config · Stores deployed specialist endpoints. · `agents/orchestrator/.agent_engine_config.json`

### Evidence Processing

Converts raw evidence into normalized observations.

- [PCAP Parser](https://github.com/benitamags/autoforensics-ai/blob/main/agents/pcap_parser/agent.py): ADK agent · Parses network captures and extracts network IOCs. · `agents/pcap_parser/agent.py`
- [Log Parser](https://github.com/benitamags/autoforensics-ai/blob/main/agents/log_parser/agent.py): ADK agent · Extracts security events and IOCs from logs. · `agents/log_parser/agent.py`

### Investigation Pipeline

Filters, enriches, detects, and synthesizes findings.

- [IOC Gating](https://github.com/benitamags/autoforensics-ai/blob/main/agents/ioc_gating/agent.py): ADK agent · Scores and filters indicators before paid or rate-limited lookups. · `agents/ioc_gating/agent.py`
- [Threat Intelligence](https://github.com/benitamags/autoforensics-ai/blob/main/agents/threat_intel/agent.py): ADK agent · Enriches approved indicators with reputation services. · `agents/threat_intel/agent.py`
- **Reputation Services**: external APIs · VirusTotal, AbuseIPDB, and optional Shodan.
- [Attack Detection](https://github.com/benitamags/autoforensics-ai/blob/main/agents/attack_detection/agent.py): ADK agent · Uses Gemini reasoning to classify activity and map MITRE ATT&CK. · `agents/attack_detection/agent.py`
- [Vulnerability Analysis](https://github.com/benitamags/autoforensics-ai/blob/main/agents/vulnerability_analysis/agent.py): ADK agent · Associates evidence with CVE and vulnerability context. · `agents/vulnerability_analysis/agent.py`
- [Timeline Builder](https://github.com/benitamags/autoforensics-ai/blob/main/agents/timeline_builder/agent.py): ADK agent · Builds attack-phase chronology from investigation results. · `agents/timeline_builder/agent.py`
- [Remediation](https://github.com/benitamags/autoforensics-ai/blob/main/agents/remediation/agent.py): ADK agent · Prioritizes P0/P1/P2 response recommendations. · `agents/remediation/agent.py`
- [Dashboard Generator](https://github.com/benitamags/autoforensics-ai/blob/main/agents/dashboard_generator/agent.py): ADK agent · 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](https://github.com/benitamags/autoforensics-ai/blob/main/shared/data_models.py): contract layer · Normalizes payloads exchanged by agents. · `shared/data_models.py`
- [Shared Constants](https://github.com/benitamags/autoforensics-ai/blob/main/shared/constants.py): policy/config layer · Provides shared conventions and enrichment configuration. · `shared/constants.py`
- **Vertex Agent Engine**: cloud runtime · Hosts independently deployed ADK agents.
- [Deployment Automation](https://github.com/benitamags/autoforensics-ai/blob/main/deploy/deploy_all.sh): operations script · Deploys, discovers, tests, updates, and cleans up the agent fleet. · `deploy/deploy_all.sh`
- [Remote URL Updater](https://github.com/benitamags/autoforensics-ai/blob/main/deploy/update_agent_urls.py): operations script · Updates orchestrator remote-agent endpoints after deployment. · `deploy/update_agent_urls.py`

## Connections

- 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