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**: <!-- Compromised / Clean / Inconclusive -->
**Confidence Level**: <!-- High / Medium / Low -->
**Report Date**: YYYY-MM-DD
**Investigator**: <!-- Agent session ID or analyst name -->

<!-- One paragraph: what was investigated, what was found, what is recommended. -->

---

## 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: <!-- Short title -->

**Status**: <!-- VALIDATED / INCONCLUSIVE / REJECTED -->

**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**: <!-- High / Medium / Low, and why -->

---

## 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`

<!-- Paste the Markdown table output from the evidence-store.py export command here -->

| 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`

<!-- Paste the chain of custody section from the export output here -->

| 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: <!-- Link to GitHub issues, CVEs, security advisories -->
- RAPTOR framework: https://github.com/gadievron/raptor