{"id":50251523,"url":"https://github.com/carlos-projects/agentforensics","last_synced_at":"2026-05-27T02:01:15.011Z","repository":{"id":360532942,"uuid":"1250502808","full_name":"Carlos-Projects/agentforensics","owner":"Carlos-Projects","description":"Post-incident forensics for AI agents — record, reconstruct, and analyze agent behavior after security events","archived":false,"fork":false,"pushed_at":"2026-05-26T20:58:26.000Z","size":68,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T21:21:05.179Z","etag":null,"topics":["agent-security","ai-agents","ai-forensics","forensic-analysis","incident-response","mcp-security","timeline-reconstruction"],"latest_commit_sha":null,"homepage":"https://github.com/Carlos-Projects/agentforensics","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Carlos-Projects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T17:40:32.000Z","updated_at":"2026-05-26T20:58:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Carlos-Projects/agentforensics","commit_stats":null,"previous_names":["carlos-projects/agentforensics"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Carlos-Projects/agentforensics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carlos-Projects%2Fagentforensics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carlos-Projects%2Fagentforensics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carlos-Projects%2Fagentforensics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carlos-Projects%2Fagentforensics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Carlos-Projects","download_url":"https://codeload.github.com/Carlos-Projects/agentforensics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carlos-Projects%2Fagentforensics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33546836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-security","ai-agents","ai-forensics","forensic-analysis","incident-response","mcp-security","timeline-reconstruction"],"created_at":"2026-05-27T02:01:13.968Z","updated_at":"2026-05-27T02:01:14.998Z","avatar_url":"https://github.com/Carlos-Projects.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentForensics 🔍⚖️\n\n[![CI](https://img.shields.io/github/actions/workflow/status/Carlos-Projects/agentforensics/ci.yml?branch=main\u0026logo=github)](https://github.com/Carlos-Projects/agentforensics/actions)\n[![PyPI version](https://img.shields.io/pypi/v/agentforensics?logo=pypi)](https://pypi.org/project/agentforensics/)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue?logo=python)](https://python.org)\n[![License](https://img.shields.io/github/license/Carlos-Projects/agentforensics?logo=opensourceinitiative)](LICENSE)\n[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen?logo=pytest)](https://github.com/Carlos-Projects/agentforensics/actions)\n[![Mypy](https://img.shields.io/badge/mypy-0%20errors-success?logo=python)](https://github.com/Carlos-Projects/agentforensics)\n[![Ruff](https://img.shields.io/badge/ruff-clean-success?logo=python)](https://github.com/Carlos-Projects/agentforensics)\n[![Docs](https://img.shields.io/badge/docs-ReadTheDocs-blue?logo=readthedocs)](https://agentforensics.readthedocs.io)\n[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa)](CODE_OF_CONDUCT.md)\n[![GitHub stars](https://img.shields.io/github/stars/Carlos-Projects/agentforensics?style=social)](https://github.com/Carlos-Projects/agentforensics)\n\n**Reconstruct what the AI agent did — after the damage is done.**\n\n---\n\n**AgentForensics** is the post-incident forensics system for autonomous AI agents. Your stack has prevention (AgentGate, MCPGuard) and detection (MCPscop, Palisade) — but when an agent goes rogue, you need **forensics**. This project closes that gap by recording, reconstructing, and analyzing agent behavior after security events.\n\nBuilt for security teams investigating AI agent incidents, AgentForensics ingests logs from MCPGuard and AgentGate, reconstructs complete behavioral timelines, replays agent actions interactively, detects policy deviations, and generates audit-ready incident reports with full chain of custody.\n\n---\n\n## What it does\n\n- **Event Ingestion** — Ingest logs from MCPGuard, AgentGate, and generic sources\n- **Timeline Reconstruction** — Build complete chronological timelines of agent behavior\n- **Behavior Replay** — Interactively replay what the agent did, step by step\n- **Policy Deviation Detection** — Detect when agents strayed from their approved policies\n- **Incident Report Generation** — Generate automated, audit-ready forensic reports\n- **Evidence Chain** — Maintain cryptographic chain of custody for all evidence\n- **Compliance Auditing** — Verify agent behavior against NIST AI RMF and internal policies\n\n## What makes it unique\n\n| Capability | **AgentForensics** | Generic Log Tools | SIEM Platforms |\n|---|---|---|---|\n| AI agent behavior replay | ✅ | ❌ | ❌ |\n| Policy deviation detection | ✅ | ❌ | Partial |\n| MCP/AgentGate native ingest | ✅ | ❌ | ❌ |\n| Chain of custody (SHA-256) | ✅ | ❌ | ❌ |\n| Interactive timeline | ✅ | Partial | Partial |\n| mcp-taxonomy integration | ✅ | ❌ | ❌ |\n\n## Quick Start\n\n```bash\n# Installation\npip install agentforensics\n\n# Or from source\ngit clone https://github.com/Carlos-Projects/agentforensics\ncd agentforensics\npip install -e \".[dev]\"\n```\n\n### CLI\n\n```bash\n# Ingest logs from multiple sources\nagentforensics ingest --mcpguard /var/log/mcpguard.jsonl --agentgate /var/log/agentgate.log\n\n# Reconstruct timeline\nagentforensics timeline\n\n# Replay agent behavior\nagentforensics replay --speed 2.0\n\n# Generate incident report\nagentforensics report --format markdown --output incident_report.md\n\n# Start web dashboard\nagentforensics serve --port 8000\n```\n\n### Docker\n\n```bash\ndocker compose up -d\n# Open http://localhost:8000\n```\n\n### Optional extras\n\n```bash\npip install agentforensics[export]   # MCPscop webhook integration (httpx)\npip install agentforensics[pdf]      # PDF report export (weasyprint)\npip install agentforensics[all]      # Everything\n```\n\n### Python API\n\n```python\nfrom agentforensics.engine import ForensicsEngine\nfrom pathlib import Path\n\nengine = ForensicsEngine()\nengine.ingest_mcpguard(Path(\"mcpguard.jsonl\"))\nengine.ingest_agentgate(Path(\"agentgate.log\"))\n\ntimeline = engine.build_timeline()\nreport = engine.generate_report(fmt=\"markdown\")\nprint(report)\n\n# Export to MCPscop dashboard\nfrom agentforensics.export import export_events_to_mcpscop\nexport_events_to_mcpscop(timeline, base_url=\"http://localhost:9000\", api_key=\"...\")\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    AgentForensics                        │\n├─────────────────────────────────────────────────────────┤\n│  CLI (Typer)          Web Dashboard (FastAPI + HTMX)    │\n├─────────────────────────────────────────────────────────┤\n│                    Forensics Engine                      │\n├──────────┬──────────────┬──────────┬────────────────────┤\n│  Ingest  │   Timeline   │  Replay  │     Reports        │\n│          │              │          │                    │\n│ MCPGuard │  Builder     │ Player   │  Incident Report   │\n│ AgentGate│  Correlator  │ Diff     │  Compliance Audit  │\n│ Generic  │  Visualizer  │ Anomaly  │  Evidence Chain    │\n├──────────┴──────────────┴──────────┴────────────────────┤\n│              SQLite + Pydantic + Plotly                  │\n└─────────────────────────────────────────────────────────┘\n         ▲                    ▲\n         │                    │\n    MCPGuard logs      AgentGate signals\n```\n\n## Dashboard\n\n![AgentForensics Dashboard](docs/source/_static/dashboard.png)\n\n*Web dashboard showing sample forensic data with event timeline, severity breakdown, and source distribution.*\n\n## Integration with the MCP Security Ecosystem\n\n- **Consumes** logs from [MCPGuard](https://github.com/Carlos-Projects/mcpguard) and signals from [AgentGate](https://github.com/Carlos-Projects/agentgate)\n- **Feeds** forensic reports to [MCPscop](https://github.com/Carlos-Projects/mcpscope) dashboard\n- **Uses** [mcp-taxonomy](https://github.com/Carlos-Projects/mcp-taxonomy) for standardized classification\n- **Follows** the same stack pattern as MCPscop (FastAPI, SQLite, Plotly, HTMX)\n\n## Documentation\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history and [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\nFull API documentation is available at [ReadTheDocs](https://agentforensics.readthedocs.io) (coming soon).\n\n## Development\n\n```bash\nmake dev-install   # Install with all extras\nmake check         # Run lint + typecheck + tests\nmake test-cov      # Run tests with coverage report\nmake docs          # Build Sphinx documentation\nmake build         # Build distribution artifacts\nmake clean         # Remove build artifacts and caches\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## Testing\n\n```bash\npython -m pytest tests/ -v\n```\n\n## Related\n\n- [MCPGuard](https://github.com/Carlos-Projects/mcpguard) — Runtime security proxy for MCP/A2A\n- [AgentGate](https://github.com/Carlos-Projects/agentgate) — Policy-based firewall for AI agents\n- [MCPscop](https://github.com/Carlos-Projects/mcpscope) — Unified security dashboard\n- [mcpwn](https://github.com/Carlos-Projects/mcpwn) — Offensive security testing for MCP\n- [palisade-scanner](https://github.com/Carlos-Projects/palisade-scanner) — Prompt injection scanner\n- [mcp-taxonomy](https://github.com/Carlos-Projects/mcp-taxonomy) — Classification taxonomy\n- [AIAO](https://aiagentobservatory.org) — AI Agent Observatory\n- [veeduria](https://veeduria.online) — Public procurement monitoring\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlos-projects%2Fagentforensics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlos-projects%2Fagentforensics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlos-projects%2Fagentforensics/lists"}