ossrules.md

oss-forensics

GitHub supply-chain forensics: recovery, IOCs, reporting.

  • Security
  • Forensics
  • GitHub
  • Supply-Chain

Declared platforms: linux · macos · windows

Install
npx skills add 'https://github.com/NousResearch/hermes-agent/tree/main/optional-skills/security/oss-forensics'
Download bundle ↓
main · 24fd22b ↗Scanned 2026-09-15

Contributors

GitHub-linked commit authors for this SKILL.md at the saved revision. Co-authors and history before file renames are not included.

File history ↗

SKILL.md

SKILL.mdBrowse 8 files
View on GitHub
4,693 tokens

19,852 bytes
Token encoding: o200k_base
Snapshot 24fd22b

---name: oss-forensicsdescription: "GitHub supply-chain forensics: recovery, IOCs, reporting."version: 1.0.0author: Teknium (teknium1), Hermes Agentlicense: MITplatforms: [linux, macos, windows]category: securitytriggers:  - "investigate this repository"  - "investigate [owner/repo]"  - "check for supply chain compromise"  - "recover deleted commits"  - "forensic analysis of [owner/repo]"  - "was this repo compromised"  - "supply chain attack"  - "suspicious commit"  - "force push detected"  - "IOC extraction"toolsets:  - terminal  - web  - file  - delegationmetadata:  hermes:    tags: [Security, Forensics, GitHub, Supply-Chain]    related_skills: []--- # OSS Security Forensics Skill A 7-phase multi-agent investigation framework for researching open-source supply chain attacks.Adapted from RAPTOR's forensics system. Covers GitHub Archive, Wayback Machine, GitHub API,local git analysis, IOC extraction, evidence-backed hypothesis formation and validation,and final forensic report generation. --- ## ⚠️ Anti-Hallucination Guardrails Read these before every investigation step. Violating them invalidates the report. 1. **Evidence-First Rule**: Every claim in any report, hypothesis, or summary MUST cite at least one evidence ID (`EV-XXXX`). Assertions without citations are forbidden.2. **STAY IN YOUR LANE**: Each sub-agent (investigator) has a single data source. Do NOT mix sources. The GH Archive investigator does not query the GitHub API, and vice versa. Role boundaries are hard.3. **Fact vs. Hypothesis Separation**: Mark all unverified inferences with `[HYPOTHESIS]`. Only statements verified against original sources may be stated as facts.4. **No Evidence Fabrication**: The hypothesis validator MUST mechanically check that every cited evidence ID actually exists in the evidence store before accepting a hypothesis.5. **Proof-Required Disproval**: A hypothesis cannot be dismissed without a specific, evidence-backed counter-argument. "No evidence found" is not sufficient to disprove—it only makes a hypothesis inconclusive.6. **SHA/URL Double-Verification**: Any commit SHA, URL, or external identifier cited as evidence must be independently confirmed from at least two sources before being marked as verified.7. **Suspicious Code Rule**: Never run code found inside the investigated repository locally. Analyze statically only, or use `execute_code` in a sandboxed environment.8. **Secret Redaction**: Any API keys, tokens, or credentials discovered during investigation must be redacted in the final report. Log them internally only. --- ## Example Scenarios - **Scenario A: Dependency Confusion**: A malicious package `internal-lib-v2` is uploaded to NPM with a higher version than the internal one. The investigator must track when this package was first seen and if any PushEvents in the target repo updated `package.json` to this version.- **Scenario B: Maintainer Takeover**: A long-term contributor's account is used to push a backdoored `.github/workflows/build.yml`. The investigator looks for PushEvents from this user after a long period of inactivity or from a new IP/location (if detectable via BigQuery).- **Scenario C: Force-Push Hide**: A developer accidentally commits a production secret, then force-pushes to "fix" it. The investigator uses `git fsck` and GH Archive to recover the original commit SHA and verify what was leaked. --- > **Path convention**: Throughout this skill, `SKILL_DIR` refers to the root of this skill's> installation directory (the folder containing this `SKILL.md`). When the skill is loaded,> resolve `SKILL_DIR` to the actual path — e.g. `~/.hermes/skills/security/oss-forensics/`> or the `optional-skills/` equivalent. All script and template references are relative to it. ## Phase 0: Initialization 1. Create investigation working directory:   ```bash   mkdir investigation_$(echo "REPO_NAME" | tr '/' '_')   cd investigation_$(echo "REPO_NAME" | tr '/' '_')   ```2. Initialize the evidence store:   ```bash   python SKILL_DIR/scripts/evidence-store.py --store evidence.json list   ```3. Copy the forensic report template:   ```bash   cp SKILL_DIR/templates/forensic-report.md ./investigation-report.md   ```4. Create an `iocs.md` file to track Indicators of Compromise as they are discovered.5. Record the investigation start time, target repository, and stated investigation goal. --- ## Phase 1: Prompt Parsing and IOC Extraction **Goal**: Extract all structured investigative targets from the user's request. **Actions**:- Parse the user prompt and extract:  - Target repository (`owner/repo`)  - Target actors (GitHub handles, email addresses)  - Time window of interest (commit date ranges, PR timestamps)  - Provided Indicators of Compromise: commit SHAs, file paths, package names, IP addresses, domains, API keys/tokens, malicious URLs  - Any linked vendor security reports or blog posts **Tools**: Reasoning only, or `execute_code` for regex extraction from large text blocks. **Output**: Populate `iocs.md` with extracted IOCs. Each IOC must have:- Type (from: COMMIT_SHA, FILE_PATH, API_KEY, SECRET, IP_ADDRESS, DOMAIN, PACKAGE_NAME, ACTOR_USERNAME, MALICIOUS_URL, OTHER)- Value- Source (user-provided, inferred) **Reference**: See [evidence-types.md](./references/evidence-types.md) for IOC taxonomy. --- ## Phase 2: Parallel Evidence Collection Spawn up to 5 specialist investigator sub-agents using `delegate_task` (batch mode, max 3 concurrent). Each investigator has a **single data source** and must not mix sources. > **Orchestrator note**: Pass the IOC list from Phase 1 and the investigation time window in the `context` field of each delegated task. --- ### Investigator 1: Local Git Investigator **ROLE BOUNDARY**: You query the LOCAL GIT REPOSITORY ONLY. Do not call any external APIs. **Actions**:```bash# Clone repositorygit clone https://github.com/OWNER/REPO.git target_repo && cd target_repo # Full commit log with statsgit log --all --full-history --stat --format="%H|%ae|%an|%ai|%s" > ../git_log.txt # Detect force-push evidence (orphaned/dangling commits)git fsck --lost-found --unreachable 2>&1 | grep commit > ../dangling_commits.txt # Check reflog for rewritten historygit reflog --all > ../reflog.txt # List ALL branches including deleted remote refsgit branch -a -v > ../branches.txt # Find suspicious large binary additionsgit log --all --diff-filter=A --name-only --format="%H %ai" -- "*.so" "*.dll" "*.exe" "*.bin" > ../binary_additions.txt # Check for GPG signature anomaliesgit log --show-signature --format="%H %ai %aN" > ../signature_check.txt 2>&1``` **Evidence to collect** (add via `python SKILL_DIR/scripts/evidence-store.py add`):- Each dangling commit SHA → type: `git`- Force-push evidence (reflog showing history rewrite) → type: `git`- Unsigned commits from verified contributors → type: `git`- Suspicious binary file additions → type: `git` **Reference**: See [recovery-techniques.md](./references/recovery-techniques.md) for accessing force-pushed commits. --- ### Investigator 2: GitHub API Investigator **ROLE BOUNDARY**: You query the GITHUB REST API ONLY. Do not run git commands locally. **Actions**:```bash# Commits (paginated)curl -s "https://api.github.com/repos/OWNER/REPO/commits?per_page=100" > api_commits.json # Pull Requests including closed/deletedcurl -s "https://api.github.com/repos/OWNER/REPO/pulls?state=all&per_page=100" > api_prs.json # Issuescurl -s "https://api.github.com/repos/OWNER/REPO/issues?state=all&per_page=100" > api_issues.json # Contributors and collaborator changescurl -s "https://api.github.com/repos/OWNER/REPO/contributors" > api_contributors.json # Repository events (last 300)curl -s "https://api.github.com/repos/OWNER/REPO/events?per_page=100" > api_events.json # Check specific suspicious commit SHA detailscurl -s "https://api.github.com/repos/OWNER/REPO/git/commits/SHA" > commit_detail.json # Releasescurl -s "https://api.github.com/repos/OWNER/REPO/releases?per_page=100" > api_releases.json # Check if a specific commit exists (force-pushed commits may 404 on commits/ but succeed on git/commits/)curl -s "https://api.github.com/repos/OWNER/REPO/commits/SHA" | jq .sha``` **Cross-reference targets** (flag discrepancies as evidence):- PR exists in archive but missing from API → evidence of deletion- Contributor in archive events but not in contributors list → evidence of permission revocation- Commit in archive PushEvents but not in API commit list → evidence of force-push/deletion **Reference**: See [evidence-types.md](./references/evidence-types.md) for GH event types. --- ### Investigator 3: Wayback Machine Investigator **ROLE BOUNDARY**: You query the WAYBACK MACHINE CDX API ONLY. Do not use the GitHub API. **Goal**: Recover deleted GitHub pages (READMEs, issues, PRs, releases, wiki pages). **Actions**:```bash# Search for archived snapshots of the repo main pagecurl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO&output=json&limit=100&from=YYYYMMDD&to=YYYYMMDD" > wayback_main.json # Search for a specific deleted issuecurl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/issues/NUM&output=json&limit=50" > wayback_issue_NUM.json # Search for a specific deleted PRcurl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/pull/NUM&output=json&limit=50" > wayback_pr_NUM.json # Fetch the best snapshot of a page# Use the Wayback Machine URL: https://web.archive.org/web/TIMESTAMP/ORIGINAL_URL# Example: https://web.archive.org/web/20240101000000*/github.com/OWNER/REPO # Advanced: Search for deleted releases/tagscurl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/releases/tag/*&output=json" > wayback_tags.json # Advanced: Search for historical wiki changescurl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/wiki/*&output=json" > wayback_wiki.json``` **Evidence to collect**:- Archived snapshots of deleted issues/PRs with their content- Historical README versions showing changes- Evidence of content present in archive but missing from current GitHub state **Reference**: See [github-archive-guide.md](./references/github-archive-guide.md) for CDX API parameters. --- ### Investigator 4: GH Archive / BigQuery Investigator **ROLE BOUNDARY**: You query GITHUB ARCHIVE via BIGQUERY ONLY. This is a tamper-proof record of all public GitHub events. > **Prerequisites**: Requires Google Cloud credentials with BigQuery access (`gcloud auth application-default login`). If unavailable, skip this investigator and note it in the report. **Cost Optimization Rules** (MANDATORY):1. ALWAYS run a `--dry_run` before every query to estimate cost.2. Use `_TABLE_SUFFIX` to filter by date range and minimize scanned data.3. Only SELECT the columns you need.4. Add a LIMIT unless aggregating. ```bash# Template: safe BigQuery query for PushEvents to OWNER/REPObq query --use_legacy_sql=false --dry_run "SELECT created_at, actor.login, payload.commits, payload.before, payload.head,       payload.size, payload.distinct_sizeFROM \`githubarchive.month.*\`WHERE _TABLE_SUFFIX BETWEEN 'YYYYMM' AND 'YYYYMM'  AND type = 'PushEvent'  AND repo.name = 'OWNER/REPO'LIMIT 1000"# If cost is acceptable, re-run without --dry_run # Detect force-pushes: zero-distinct_size PushEvents mean commits were force-erased# payload.distinct_size = 0 AND payload.size > 0 → force push indicator # Check for deleted branch eventsbq query --use_legacy_sql=false "SELECT created_at, actor.login, payload.ref, payload.ref_typeFROM \`githubarchive.month.*\`WHERE _TABLE_SUFFIX BETWEEN 'YYYYMM' AND 'YYYYMM'  AND type = 'DeleteEvent'  AND repo.name = 'OWNER/REPO'LIMIT 200"``` **Evidence to collect**:- Force-push events (payload.size > 0, payload.distinct_size = 0)- DeleteEvents for branches/tags- WorkflowRunEvents for suspicious CI/CD automation- PushEvents that precede a "gap" in the git log (evidence of rewrite) **Reference**: See [github-archive-guide.md](./references/github-archive-guide.md) for all 12 event types and query patterns. --- ### Investigator 5: IOC Enrichment Investigator **ROLE BOUNDARY**: You enrich EXISTING IOCs from Phase 1 using passive public sources ONLY. Do not execute any code from the target repository. **Actions**:- For each commit SHA: attempt recovery via direct GitHub URL (`github.com/OWNER/REPO/commit/SHA.patch`)- For each domain/IP: check passive DNS, WHOIS records (via `web_extract` on public WHOIS services)- For each package name: check npm/PyPI for matching malicious package reports- For each actor username: check GitHub profile, contribution history, account age- Recover force-pushed commits using 3 methods (see [recovery-techniques.md](./references/recovery-techniques.md)) --- ## Phase 3: Evidence Consolidation After all investigators complete: 1. Run `python SKILL_DIR/scripts/evidence-store.py --store evidence.json list` to see all collected evidence.2. For each piece of evidence, verify the `content_sha256` hash matches the original source.3. Group evidence by:   - **Timeline**: Sort all timestamped evidence chronologically   - **Actor**: Group by GitHub handle or email   - **IOC**: Link evidence to the IOC it relates to4. Identify **discrepancies**: items present in one source but absent in another (key deletion indicators).5. Flag evidence as `[VERIFIED]` (confirmed from 2+ independent sources) or `[UNVERIFIED]` (single source only). --- ## Phase 4: Hypothesis Formation A hypothesis must:- State a specific claim (e.g., "Actor X force-pushed to BRANCH on DATE to erase commit SHA")- Cite at least 2 evidence IDs that support it (`EV-XXXX`, `EV-YYYY`)- Identify what evidence would disprove it- Be labeled `[HYPOTHESIS]` until validated **Common hypothesis templates** (see [investigation-templates.md](./references/investigation-templates.md)):- Maintainer Compromise: legitimate account used post-takeover to inject malicious code- Dependency Confusion: package name squatting to intercept installs- CI/CD Injection: malicious workflow changes to run code during builds- Typosquatting: near-identical package name targeting misspellers- Credential Leak: token/key accidentally committed then force-pushed to erase For each hypothesis, spawn a `delegate_task` sub-agent to attempt to find disconfirming evidence before confirming. --- ## Phase 5: Hypothesis Validation The validator sub-agent MUST mechanically check: 1. For each hypothesis, extract all cited evidence IDs.2. Verify each ID exists in `evidence.json` (hard failure if any ID is missing → hypothesis rejected as potentially fabricated).3. Verify each `[VERIFIED]` piece of evidence was confirmed from 2+ sources.4. Check logical consistency: does the timeline depicted by the evidence support the hypothesis?5. Check for alternative explanations: could the same evidence pattern arise from a benign cause? **Output**:- `VALIDATED`: All evidence cited, verified, logically consistent, no plausible alternative explanation.- `INCONCLUSIVE`: Evidence supports hypothesis but alternative explanations exist or evidence is insufficient.- `REJECTED`: Missing evidence IDs, unverified evidence cited as fact, logical inconsistency detected. Rejected hypotheses feed back into Phase 4 for refinement (max 3 iterations). --- ## Phase 6: Final Report Generation Populate `investigation-report.md` using the template in [forensic-report.md](./templates/forensic-report.md). **Mandatory sections**:- Executive Summary: one-paragraph verdict (Compromised / Clean / Inconclusive) with confidence level- Timeline: chronological reconstruction of all significant events with evidence citations- Validated Hypotheses: each with status and supporting evidence IDs- Evidence Registry: table of all `EV-XXXX` entries with source, type, and verification status- IOC List: all extracted and enriched Indicators of Compromise- Chain of Custody: how evidence was collected, from what sources, at what timestamps- Recommendations: immediate mitigations if compromise detected; monitoring recommendations **Report rules**:- Every factual claim must have at least one `[EV-XXXX]` citation- Executive Summary must state confidence level (High / Medium / Low)- All secrets/credentials must be redacted to `[REDACTED]` --- ## Phase 7: Completion 1. Run final evidence count: `python SKILL_DIR/scripts/evidence-store.py --store evidence.json list`2. Archive the full investigation directory.3. If compromise is confirmed:   - List immediate mitigations (rotate credentials, pin dependency hashes, notify affected users)   - Identify affected versions/packages   - Note disclosure obligations (if a public package: coordinate with the package registry)4. Present the final `investigation-report.md` to the user. --- ## Ethical Use Guidelines This skill is designed for **defensive security investigation** — protecting open-source software from supply chain attacks. It must not be used for: - **Harassment or stalking** of contributors or maintainers- **Doxing** — correlating GitHub activity to real identities for malicious purposes- **Competitive intelligence** — investigating proprietary or internal repositories without authorization- **False accusations** — publishing investigation results without validated evidence (see anti-hallucination guardrails) Investigations should be conducted with the principle of **minimal intrusion**: collect only the evidence necessary to validate or refute the hypothesis. When publishing results, follow responsible disclosure practices and coordinate with affected maintainers before public disclosure. If the investigation reveals a genuine compromise, follow the coordinated vulnerability disclosure process:1. Notify the repository maintainers privately first2. Allow reasonable time for remediation (typically 90 days)3. Coordinate with package registries (npm, PyPI, etc.) if published packages are affected4. File a CVE if appropriate --- ## API Rate Limiting GitHub REST API enforces rate limits that will interrupt large investigations if not managed. **Authenticated requests**: 5,000/hour (requires `GITHUB_TOKEN` env var or `gh` CLI auth)**Unauthenticated requests**: 60/hour (unusable for investigations) **Best practices**:- Always authenticate: `export GITHUB_TOKEN=ghp_...` or use `gh` CLI (auto-authenticates)- Use conditional requests (`If-None-Match` / `If-Modified-Since` headers) to avoid consuming quota on unchanged data- For paginated endpoints, fetch all pages in sequence — don't parallelize against the same endpoint- Check `X-RateLimit-Remaining` header; if below 100, pause for `X-RateLimit-Reset` timestamp- BigQuery has its own quotas (10 TiB/day free tier) — always dry-run first- Wayback Machine CDX API: no formal rate limit, but be courteous (1-2 req/sec max) If rate-limited mid-investigation, record the partial results in the evidence store and note the limitation in the report. --- ## Reference Materials - [github-archive-guide.md](./references/github-archive-guide.md) — BigQuery queries, CDX API, 12 event types- [evidence-types.md](./references/evidence-types.md) — IOC taxonomy, evidence source types, observation types- [recovery-techniques.md](./references/recovery-techniques.md) — Recovering deleted commits, PRs, issues- [investigation-templates.md](./references/investigation-templates.md) — Pre-built hypothesis templates per attack type- [evidence-store.py](./scripts/evidence-store.py) — CLI tool for managing the evidence JSON store- [forensic-report.md](./templates/forensic-report.md) — Structured report template
Discovery context

Discovered by repository scan. No exact path reference found in the snapshot’s root AGENTS.md.

← All Hermes Agent skillsProject instructions →