This content originally appeared on DEV Community and was authored by pete
System: MatrixSwarm Infrastructure
Component: forensic_detective agent
Purpose: Correlate, analyze, and elevate status reports from the hive into structured, intelligent incident forensics.
What Is ForensicDetective?
forensic_detective is not a logger.
It’s a real-time forensic correlation engine inside your swarm. When other agents report warnings, failures, or breaches, forensic_detective builds a story from the noise:
- Who triggered what.
- What other events happened in the same window.
- Why it matters.
- And what to do about it (with or without AI).
Core Capabilities
1. Structured Event Ingestion
Listens to incoming reports via:
role: hive.forensics.data_feed@cmd_ingest_status_report
Receives events from agents like:
gatekeepernginx_watchdogsystem_healthnetwork_healthghost_wire
2. Event Hashing + Buffering
Every event is hashed (minus timestamp) to avoid dupes. Stored in a rotating buffer:
- Default: last 100 events
- Retention: 120 seconds
This creates a live memory of what just happened across your infrastructure.
3. Critical Event Triggering
When an incoming report has:
"severity": "CRITICAL"
It:
- Checks cooldown per service (default: 300s)
- Assigns a unique incident UUID
- Triggers the full forensic process
4. Event Correlation
All buffered events in the last 120s are pulled in. This is how you get context:
"Nginx crashed" alone means nothing.
But "Nginx crashed + disk 95% full + CPU spike + login from China" means everything.
5. Forensic Report Generation
Loads a per-service Python module dynamically:
from forensic_detective.factory.watchdog.nginx.investigator import Investigator
If found, it runs:
add_specific_findings(findings)
And appends insight to the incident.
No module? No problem. It still builds a default report.
6. Alert Broadcasting
Once analysis is done:
- Formats an alert embed (
title,description,incident ID) - Sends it to:
hive.alert@cmd_send_alert_msg - Includes full findings, even if the analysis says: "Your disk is full, genius."
7. Oracle Integration (Optional)
If enabled:
"oracle_analysis": {
"enable_oracle": 1,
"role": "hive.oracle"
}
Then the detective sends a GPT-style prompt like:
"CPU high. Nginx failed. Disk at 99%. What happened? What should we do?"
Oracle responds with a full RCA + command steps.
It gets rebroadcast under:
## AI-Enhanced Analysis
If enabled in config:
"oracle_analysis": { "enable_oracle": 1, "role": "hive.oracle" }
Sends a structured prompt (critical event + preceding context) to an Oracle AI.
Oracle responds with root cause + remediation steps.
forensic_detective rebroadcasts as a AI-Enhanced Analysis alert, which can piped to Slack, Telegram, Discord, Email, etc
And logged.
8. Postmortem File Saved
Every triggered incident gets saved to:
/swarm/sessions/your_agent/summary/YYYYMMDD-nginx-failure.json
Contents:
- Incident ID
- Timestamp
- Critical event
- All correlated events
- Full forensic report (Oracle + local)
Why It Matters
| Problem | Without FD | With ForensicDetective |
|---|---|---|
| Nginx went down | You grep logs for 10 mins | Instant report w/ root cause |
| Alerts spam you | All say "HIGH CPU" | One incident. One cause. Full stack trace. |
| No traceability | Logs rotated | JSON archive with context + command steps |
| No escalation | You miss the trend | FD ties related events into a single actionable failure |
How To Enable It
- In your directive:
{
"universal_id": "forensic-detective-1",
"name": "forensic_detective",
"config": {
"oracle_analysis": {
"enable_oracle": 1,
"role": "hive.oracle"
},
"alert_to_role": "hive.alert"
},
"service-manager": [
{
"role": ["hive.forensics.data_feed@cmd_ingest_status_report"]
}
]
}
- Make your agents report structured events using:
send_status_report(status, severity, details, metrics)
- Optional: Drop in your own custom factory:
forensic_detective/factory/watchdog/nginx/investigator.py
With a function:
def add_specific_findings(self, findings):
findings.append("nginx failed due to repeated 502 errors")
return findings
Resources
GitHub: https://github.com/matrixswarm/matrixos
GitHub: https://github.com/matrixswarm/phoenix
Docs: https://matrixswarm.com
Discord: https://discord.gg/CyngHqDmku
Telegram: https://t.me/matrixswarm
Python: pip install matrixswarm
Codex: /agents/gatekeeper
X/Twitter: @matrixswarm
💬 Join the Hive:
Join the Swarm: https://discord.gg/CyngHqDmku
Report bugs, fork the swarm, or log your own Codex banner.
This content originally appeared on DEV Community and was authored by pete
pete | Sciencx (2025-09-30T06:03:53+00:00) ForensicDetective: When You Don’t Have Time to Read 80,000 Lines of Garbage. Retrieved from https://www.scien.cx/2025/09/30/forensicdetective-when-you-dont-have-time-to-read-80000-lines-of-garbage/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.