c30505dddd
* feat: add OSS Security Forensics skill (Skills Hub) Salvaged from PR #1066 by zagiscoming. Adds a 7-phase multi-agent investigation framework for GitHub supply chain attack forensics. Skill contents (optional-skills/security/oss-forensics/): - SKILL.md: 420-line investigation framework with 8 anti-hallucination guardrails, 5 specialist investigators, ethical use guidelines, and API rate limiting guidance - evidence-store.py: CLI evidence manager with add/list/verify/query/ export/summary + SHA-256 integrity + chain of custody - references/: evidence types, GH Archive BigQuery guide (expanded with 12 event types and 6 query templates), recovery techniques (4 methods), investigation templates (5 attack patterns) - templates/: forensic report template (151 lines), malicious package report template Changes from original PR: - Dropped unrelated core tool changes (delegate_tool.py role parameter, AGENTS.md, README.md modifications) - Removed duplicate skills/security/oss-forensics/ placement - Fixed github-archive-guide.md (missing from optional-skills/, expanded from 33 to 160+ lines with all 12 event types and query templates) - Added ethical use guidelines and API rate limiting sections - Rewrote tests to match the v2 evidence store API (12 tests, all pass) Closes #384 * fix: use python3 and SKILL_DIR paths throughout oss-forensics skill - Replace all 'python' invocations with 'python3' for portability (Ubuntu doesn't ship 'python' by default) - Replace relative '../scripts/' and '../templates/' paths with SKILL_DIR/scripts/ and SKILL_DIR/templates/ convention - Add path convention note before Phase 0 explaining SKILL_DIR - Fix double --- separator (cosmetic) - Applies to SKILL.md, evidence-store.py docstring, recovery-techniques.md, and forensic-report.md template --------- Co-authored-by: zagiscoming <zagiscoming@users.noreply.github.com>
4.7 KiB
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: runpython3 SKILL_DIR/scripts/evidence-store.py --store evidence.json verify) - Related issues:
- RAPTOR framework: https://github.com/gadievron/raptor