hermes-agent/optional-skills/security/oss-forensics/templates/forensic-report.md

Forensic Investigation Report

Instructions: Fill in all sections. Every factual claim must cite at least one [EV-XXXX] evidence ID. Remove placeholder text and instruction notes before finalizing. Redact all secrets to [REDACTED].

---

Executive Summary

Target Repository: OWNER/REPO Investigation Period: YYYY-MM-DD to YYYY-MM-DD Verdict: Confidence Level: Report Date: YYYY-MM-DD Investigator:

---

Timeline of Events

All timestamps in UTC. Each event must cite at least one evidence ID.

Timestamp (UTC)	Event	Evidence IDs	Source
YYYY-MM-DDTHH:MM:SSZ	Describe event	[EV-XXXX]	git / gh_api / gh_archive / web_archive

---

Validated Hypotheses

Hypothesis 1:

Status:

Claim: Full statement of the hypothesis.

Supporting Evidence:

• [EV-XXXX]: What this evidence shows
• [EV-YYYY]: What this evidence shows

Counter-Evidence Considered: What might disprove this, and why it was ruled out or not.

Confidence:

---

Indicators of Compromise (IOC List)

Type	Value	Status	Evidence
COMMIT_SHA	abc123...	Confirmed malicious	[EV-XXXX]
ACTOR_USERNAME	handle	Suspected compromised	[EV-YYYY]
FILE_PATH	src/evil.js	Confirmed malicious	[EV-ZZZZ]
DOMAIN	evil-cdn.io	Confirmed C2	[EV-WWWW]

---

Affected Versions

Version / Tag	Published	Contains Malicious Code	Evidence
v1.2.3	YYYY-MM-DD	Yes / No / Unknown	[EV-XXXX]

---

Evidence Registry

Generated by: python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json export

ID	Type	Source	Actor	Verification	Event Timestamp	URL
EV-0001

---

Chain of Custody

Generated by: python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json export

Evidence ID	Action	Timestamp	Source
EV-0001	add

---

Technical Findings

Git History Analysis

Summarize findings from local git analysis: dangling commits, reflog anomalies, unsigned commits, binary additions, etc.

GitHub API Analysis

Summarize findings from GitHub REST API: deleted PRs/issues, contributor changes, release anomalies, etc.

GitHub Archive Analysis

Summarize findings from BigQuery: force-push events, delete events, workflow anomalies, member changes, etc. Note: If BigQuery was unavailable, state this explicitly.

Wayback Machine Analysis

Summarize findings from archive.org: recovered deleted pages, historical content differences, etc.

IOC Enrichment

Summarize enrichment results: WHOIS data for domains, recovered commit content, actor account analysis, etc.

---

Recommendations

Immediate Actions (If Compromise Confirmed)

• Rotate all GitHub tokens, API keys, and credentials that may have been exposed
• Pin dependency versions to hashes in all affected packages
• Publish a security advisory / CVE if applicable
• Notify downstream users/package registries (npm, PyPI, etc.)
• Revoke access for the compromised account and re-secure with hardware 2FA
• Audit all CI/CD workflow files for unauthorized modifications
• Review all releases published during the compromise window

Monitoring Recommendations

• Enable branch protection on main/master (require code review, disallow force-push)
• Enable required commit signing (GPG/SSH)
• Set up GitHub audit log streaming for future monitoring
• Pin critical dependencies to known-good SHAs in lock files

---

Limitations and Caveats

• List any data sources that were unavailable (e.g., no BigQuery access)
• Note any evidence that is single-source only (not independently verified)
• Note any hypotheses that could not be confirmed or denied

---

References

• Evidence store: evidence.json (SHA-256 integrity: run python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json verify)
• Related issues:
• RAPTOR framework: https://github.com/gadievron/raptor