mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
feat: add OSS Security Forensics skill (Skills Hub) (#1482)
* 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>
This commit is contained in:
Teknium
GitHub
parent
70e24d77a1
commit
c30505dddd
9 changed files with 1683 additions and 0 deletions
|
|
@ -0,0 +1,151 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue