Oss Forensics

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:

   mkdir investigation_$(echo "REPO_NAME" | tr '/' '_')
   cd investigation_$(echo "REPO_NAME" | tr '/' '_')

2. Initialize the evidence store:

   python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json list

3. Copy the forensic report template:

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

# Clone repository
git clone https://github.com/OWNER/REPO.git target_repo && cd target_repo

# Full commit log with stats
git 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 history
git reflog --all > ../reflog.txt

# List ALL branches including deleted remote refs
git branch -a -v > ../branches.txt

# Find suspicious large binary additions
git log --all --diff-filter=A --name-only --format="%H %ai" -- "*.so" "*.dll" "*.exe" "*.bin" > ../binary_additions.txt

# Check for GPG signature anomalies
git log --show-signature --format="%H %ai %aN" > ../signature_check.txt 2>&1

Evidence to collect (add via python3 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 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:

# Commits (paginated)
curl -s "https://api.github.com/repos/OWNER/REPO/commits?per_page=100" > api_commits.json

# Pull Requests including closed/deleted
curl -s "https://api.github.com/repos/OWNER/REPO/pulls?state=all&per_page=100" > api_prs.json

# Issues
curl -s "https://api.github.com/repos/OWNER/REPO/issues?state=all&per_page=100" > api_issues.json

# Contributors and collaborator changes
curl -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 details
curl -s "https://api.github.com/repos/OWNER/REPO/git/commits/SHA" > commit_detail.json

# Releases
curl -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 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:

# Search for archived snapshots of the repo main page
curl -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 issue
curl -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 PR
curl -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/tags
curl -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 changes
curl -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 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.

# Template: safe BigQuery query for PushEvents to OWNER/REPO
bq query --use_legacy_sql=false --dry_run "
SELECT created_at, actor.login, payload.commits, payload.before, payload.head,
       payload.size, payload.distinct_size
FROM \`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 events
bq query --use_legacy_sql=false "
SELECT created_at, actor.login, payload.ref, payload.ref_type
FROM \`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 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)

---

Phase 3: Evidence Consolidation

After all investigators complete:

1. Run python3 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 to

4. 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):

• 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.

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: python3 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 first 2. Allow reasonable time for remediation (typically 90 days) 3. Coordinate with package registries (npm, PyPI, etc.) if published packages are affected 4. 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 — BigQuery queries, CDX API, 12 event types
• evidence-types.md — IOC taxonomy, evidence source types, observation types
• recovery-techniques.md — Recovering deleted commits, PRs, issues
• investigation-templates.md — Pre-built hypothesis templates per attack type
• evidence-store.py — CLI tool for managing the evidence JSON store
• forensic-report.md — Structured report template

Evidence Types Reference

Taxonomy of all evidence types, IOC types, GitHub event types, and observation types used in OSS forensic investigations.

---

Evidence Source Types

---

IOC Types

---

GitHub Archive Event Types (12 Types)

---

Evidence Verification States

Only multi_source_verified evidence may be cited as fact in validated hypotheses. unverified and single_source evidence must be labeled [UNVERIFIED] or [SINGLE-SOURCE].

---

Observation Types (Patterned after RAPTOR)

GitHub Archive Query Guide (BigQuery)

GitHub Archive records every public event on GitHub as immutable JSON records. This data is accessible via Google BigQuery and is the most reliable source for forensic investigation — events cannot be deleted or modified after recording.

Public Dataset

• Project: githubarchive
• Tables: day.YYYYMMDD, month.YYYYMM, year.YYYY
• Cost: $6.25 per TiB scanned. Always run dry runs first.
• Access: Requires a Google Cloud account with BigQuery enabled. Free tier includes 1 TiB/month of queries.

---

The 12 GitHub Event Types

---

Query Templates

Basic: All Events for a Repository

SELECT
  created_at,
  type,
  actor.login,
  repo.name,
  payload
FROM
  `githubarchive.day.20240101`  -- Adjust date
WHERE
  repo.name = 'owner/repo'
  AND type IN ('PushEvent', 'DeleteEvent', 'MemberEvent')
ORDER BY
  created_at ASC

Force-Push Detection

Force-pushes produce PushEvents where commits are overwritten. Key indicators:

• payload.distinct_size = 0 with payload.size > 0 → commits were erased
• payload.before contains the SHA before the rewrite (recoverable)

SELECT
  created_at,
  actor.login,
  JSON_EXTRACT_SCALAR(payload, '$.before') AS before_sha,
  JSON_EXTRACT_SCALAR(payload, '$.head') AS after_sha,
  JSON_EXTRACT_SCALAR(payload, '$.size') AS total_commits,
  JSON_EXTRACT_SCALAR(payload, '$.distinct_size') AS distinct_commits,
  JSON_EXTRACT_SCALAR(payload, '$.ref') AS branch_ref
FROM
  `githubarchive.month.*`
WHERE
  _TABLE_SUFFIX BETWEEN '202401' AND '202403'
  AND type = 'PushEvent'
  AND repo.name = 'owner/repo'
  AND CAST(JSON_EXTRACT_SCALAR(payload, '$.distinct_size') AS INT64) = 0
ORDER BY
  created_at ASC

Deleted Branch/Tag Detection

SELECT
  created_at,
  actor.login,
  JSON_EXTRACT_SCALAR(payload, '$.ref') AS deleted_ref,
  JSON_EXTRACT_SCALAR(payload, '$.ref_type') AS ref_type
FROM
  `githubarchive.month.*`
WHERE
  _TABLE_SUFFIX BETWEEN '202401' AND '202403'
  AND type = 'DeleteEvent'
  AND repo.name = 'owner/repo'
ORDER BY
  created_at ASC

Collaborator Permission Changes

SELECT
  created_at,
  actor.login,
  JSON_EXTRACT_SCALAR(payload, '$.action') AS action,
  JSON_EXTRACT_SCALAR(payload, '$.member.login') AS member
FROM
  `githubarchive.month.*`
WHERE
  _TABLE_SUFFIX BETWEEN '202401' AND '202403'
  AND type = 'MemberEvent'
  AND repo.name = 'owner/repo'
ORDER BY
  created_at ASC

CI/CD Workflow Activity

SELECT
  created_at,
  actor.login,
  JSON_EXTRACT_SCALAR(payload, '$.action') AS action,
  JSON_EXTRACT_SCALAR(payload, '$.workflow_run.name') AS workflow_name,
  JSON_EXTRACT_SCALAR(payload, '$.workflow_run.conclusion') AS conclusion,
  JSON_EXTRACT_SCALAR(payload, '$.workflow_run.head_sha') AS head_sha
FROM
  `githubarchive.month.*`
WHERE
  _TABLE_SUFFIX BETWEEN '202401' AND '202403'
  AND type = 'WorkflowRunEvent'
  AND repo.name = 'owner/repo'
ORDER BY
  created_at ASC

Actor Activity Profiling

SELECT
  type,
  COUNT(*) AS event_count,
  MIN(created_at) AS first_event,
  MAX(created_at) AS last_event
FROM
  `githubarchive.month.*`
WHERE
  _TABLE_SUFFIX BETWEEN '202301' AND '202412'
  AND actor.login = 'suspicious-username'
GROUP BY type
ORDER BY event_count DESC

---

Cost Optimization (MANDATORY)

1. Always dry run first: Add --dry_run flag to bq query to see estimated bytes scanned before executing. 2. Use `_TABLE_SUFFIX`: Narrow the date range as much as possible. day.* tables are cheapest for narrow windows; month.* for broader sweeps. 3. Select only needed columns: Avoid SELECT *. The payload column is large — only select specific JSON paths. 4. Add LIMIT: Use LIMIT 1000 during exploration. Remove only for final exhaustive queries. 5. Column filtering in WHERE: Filter on indexed columns (type, repo.name, actor.login) before payload extraction.

Cost estimation: A single month of GH Archive data is ~1-2 TiB uncompressed. Querying a specific repo + event type with _TABLE_SUFFIX typically scans 1-10 GiB ($0.006-$0.06).

---

Accessing via Hermes

Option A: BigQuery CLI (if gcloud is installed)

bq query --use_legacy_sql=false --format=json "YOUR QUERY"

Option B: Python (via execute_code)

from google.cloud import bigquery
client = bigquery.Client()
query = "YOUR QUERY"
results = client.query(query).result()
for row in results:
    print(dict(row))

Option C: No GCP credentials available If BigQuery is unavailable, document this limitation in the report. Use the other 4 investigators (Git, GitHub API, Wayback Machine, IOC Enrichment) — they cover most investigation needs without BigQuery.

Investigation Templates

Pre-built hypothesis and investigation templates for common supply chain attack scenarios. Each template includes: attack pattern, key evidence to collect, and hypothesis starters.

---

Template 1: Maintainer Account Compromise

Pattern: Attacker gains access to a legitimate maintainer account (phishing, credential stuffing) and uses it to push malicious code, create backdoored releases, or exfiltrate CI secrets.

Real-world examples: XZ Utils (2024), Codecov (2021), event-stream (2018)

Key Evidence to Collect:

• [ ] Push events from maintainer account outside normal working hours/timezone
• [ ] Commits adding new dependencies, obfuscated code, or modified build scripts
• [ ] Release creation immediately after suspicious push (to maximize package distribution)
• [ ] MemberEvent adding unknown collaborators (attacker adding backup access)
• [ ] WorkflowRunEvent with unexpected secret access or exfiltration-like behavior
• [ ] Account login location changes (check social media, conference talks for corroboration)

Hypothesis Starters:

[HYPOTHESIS] Actor <HANDLE>'s account was compromised on or around <DATE>, 
based on anomalous commit timing [EV-XXXX] and geographic access patterns [EV-YYYY].

[HYPOTHESIS] Release <VERSION> was published by the compromised account to push 
malicious code to downstream users, evidenced by the malicious commit [EV-XXXX] 
being added <N> hours before the release [EV-YYYY].

---

Template 2: Malicious Dependency Injection

Pattern: A trusted package is modified to include malicious code in a dependency, or a new malicious dependency is injected into an existing package.

Key Evidence to Collect:

• [ ] Diff of package.json/requirements.txt/go.mod before and after suspicious commit
• [ ] The new dependency's publication timestamp vs. the injection commit timestamp
• [ ] Whether the new dependency exists on npm/PyPI and who owns it
• [ ] Any obfuscation patterns in the injected dependency code
• [ ] Install-time scripts (postinstall, setup.py, etc.) that execute code on install

Hypothesis Starters:

[HYPOTHESIS] Commit <SHA> [EV-XXXX] introduced dependency <PACKAGE@VERSION> 
which appears to be a malicious package published by actor <HANDLE> [EV-YYYY], 
designed to execute <BEHAVIOR> during installation.

---

Template 3: CI/CD Pipeline Injection

Pattern: Attacker modifies GitHub Actions workflows to steal secrets, exfiltrate code, or inject malicious artifacts into the build output.

Key Evidence to Collect:

• [ ] Diff of all .github/workflows/*.yml files before/after suspicious period
• [ ] WorkflowRunEvents triggered by the modified workflows
• [ ] Any curl, wget, or network calls added to workflow steps
• [ ] New or modified env: sections referencing secrets.*
• [ ] Artifacts produced by modified workflow runs

Hypothesis Starters:

[HYPOTHESIS] Workflow file <FILE> was modified in commit <SHA> [EV-XXXX] to 
exfiltrate repository secrets via <METHOD>, as evidenced by the added network 
call pattern [EV-YYYY].

---

Template 4: Typosquatting / Dependency Confusion

Pattern: Attacker registers a package with a name similar to a popular package (or an internal package name) to intercept installs from users who mistype.

Key Evidence to Collect:

• [ ] Registration timestamp of the suspicious package on the registry
• [ ] Package content: does it contain malicious code or is it a stub?
• [ ] Download statistics for the suspicious package
• [ ] Names of internal packages that could be targeted (if private repo scope)
• [ ] Any references to the legitimate package in the malicious one's metadata

Hypothesis Starters:

[HYPOTHESIS] Package <MALICIOUS_NAME> was registered on <DATE> [EV-XXXX] to 
typosquat on <LEGITIMATE_NAME>, targeting users who misspell the package name. 
The package contains <BEHAVIOR> [EV-YYYY].

---

Template 5: Force-Push History Rewrite (Evidence Erasure)

Pattern: After a malicious commit is detected (or before wider notice), the attacker force-pushes to remove the malicious commit from branch history.

Detection is key — this template focuses on proving the erasure happened.

Key Evidence to Collect:

• [ ] GH Archive PushEvent with distinct_size=0 (force push indicator) [EV-XXXX]
• [ ] The SHA of the commit BEFORE the force push (from GH Archive payload.before)
• [ ] Recovery of the erased commit via direct URL or git fetch origin SHA
• [ ] Wayback Machine snapshot of the commit page before erasure
• [ ] Timeline gap in git log (N commits visible in archive but M < N in current repo)

Hypothesis Starters:

[HYPOTHESIS] Actor <HANDLE> force-pushed branch <BRANCH> on <DATE> [EV-XXXX] 
to erase commit <SHA> [EV-YYYY], which contained <MALICIOUS_CONTENT>. 
The erased commit was recovered via <METHOD> [EV-ZZZZ].

---

Cross-Cutting Investigation Checklist

Apply to every investigation regardless of template:

• [ ] Check all contributors for newly created accounts (< 30 days old at time of malicious activity)
• [ ] Check if any maintainer account changed email in the period (sign of account takeover)
• [ ] Verify GPG signatures on suspicious commits match known maintainer keys
• [ ] Check if the repository changed ownership or transferred orgs near the incident
• [ ] Look for "cleanup" commits immediately after the malicious commit (cover-up pattern)
• [ ] Check related packages/repos by the same author for similar patterns

Deleted Content Recovery Techniques

Key Insight: GitHub Never Fully Deletes Force-Pushed Commits

Force-pushed commits are removed from the branch history but REMAIN on GitHub's servers until garbage collection runs (which can take weeks to months). This is the foundation of deleted commit recovery.

---

Method 1: Direct GitHub URL (Fastest — No Auth Required)

If you have a commit SHA, access it directly even if it was force-pushed off a branch:

# View commit metadata
curl -s "https://github.com/OWNER/REPO/commit/SHA"

# Download as patch (includes full diff)
curl -s "https://github.com/OWNER/REPO/commit/SHA.patch" > recovered_commit.patch

# Download as diff
curl -s "https://github.com/OWNER/REPO/commit/SHA.diff" > recovered_commit.diff

# Example (Istio credential leak - real incident):
curl -s "https://github.com/istio/istio/commit/FORCE_PUSHED_SHA.patch"

When this works: SHA is known (from GH Archive, Wayback Machine, or git fsck) When this fails: GitHub has already garbage-collected the object (rare, typically 30–90 days post-force-push)

---

Method 2: GitHub REST API

# Works for commits force-pushed off branches but still on server
# Note: /commits/SHA may 404, but /git/commits/SHA often succeeds for orphaned commits
curl -s "https://api.github.com/repos/OWNER/REPO/git/commits/SHA" | jq .

# Get the tree (file listing) of a force-pushed commit
curl -s "https://api.github.com/repos/OWNER/REPO/git/trees/SHA?recursive=1" | jq .

# Get a specific file from a force-pushed commit
curl -s "https://api.github.com/repos/OWNER/REPO/contents/PATH?ref=SHA" | jq .content | base64 -d

---

Method 3: Git Fetch by SHA (Local — Requires Clone)

# Fetch an orphaned commit directly by SHA into local repo
cd target_repo
git fetch origin SHA
git log FETCH_HEAD -1   # view the commit
git diff FETCH_HEAD~1 FETCH_HEAD  # view the diff

# If the SHA was recently force-pushed it will still be fetchable
# This stops working once GitHub GC runs

---

Method 4: Dangling Commits via git fsck

cd target_repo

# Find all unreachable objects (includes force-pushed commits)
git fsck --unreachable --no-reflogs 2>&1 | grep "unreachable commit" | awk '{print $3}' > dangling_shas.txt

# For each dangling commit, get its metadata
while read sha; do
  echo "=== $sha ===" >> dangling_details.txt
  git show --stat "$sha" >> dangling_details.txt 2>&1
done < dangling_shas.txt

# Note: dangling objects only exist in LOCAL clone — not the same as GitHub's copies
# GitHub's copies are accessible via Methods 1-3 until GC runs

---

Recovering Deleted GitHub Issues and PRs

Via Wayback Machine CDX API

# Find all archived snapshots of a specific issue
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/issues/NUMBER&output=json&limit=50&fl=timestamp,statuscode,original" | python3 -m json.tool

# Fetch the best snapshot
# Use the timestamp from the CDX result:
# https://web.archive.org/web/TIMESTAMP/https://github.com/OWNER/REPO/issues/NUMBER
curl -s "https://web.archive.org/web/TIMESTAMP/https://github.com/OWNER/REPO/issues/NUMBER" > issue_NUMBER_archived.html

# Find all snapshots of the repo in a date range
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO*&output=json&from=20240101&to=20240201&limit=200&fl=timestamp,urlkey,statuscode" | python3 -m json.tool

Via GitHub API (Limited — Only Non-Deleted Content)

# Closed issues (not deleted) are retrievable
curl -s "https://api.github.com/repos/OWNER/REPO/issues?state=closed&per_page=100" | jq '.[].number'

# Note: DELETED issues/PRs do NOT appear in the API. Use Wayback Machine or GH Archive for those.

Via GitHub Archive (For Event History — Not Content)

-- Find all IssueEvents for a repo in a date range
SELECT created_at, actor.login, payload.action, payload.issue.number, payload.issue.title
FROM `githubarchive.day.*`
WHERE _TABLE_SUFFIX BETWEEN '20240101' AND '20240201'
  AND type = 'IssuesEvent'
  AND repo.name = 'OWNER/REPO'
ORDER BY created_at

---

Recovering Deleted Files from a Known Commit

# If you have the commit SHA (even force-pushed):
git show SHA:path/to/file.py > recovered_file.py

# Or via API (base64 encoded content):
curl -s "https://api.github.com/repos/OWNER/REPO/contents/path/to/file.py?ref=SHA" | python3 -c "
import sys, json, base64
d = json.load(sys.stdin)
print(base64.b64decode(d['content']).decode())
"

---

Evidence Recording

After recovering any deleted content, immediately record it:

python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json add \
  --source "git fetch origin FORCE_PUSHED_SHA" \
  --content "Recovered commit: FORCE_PUSHED_SHA | Author: attacker@example.com | Date: 2024-01-15 | Added file: malicious.sh" \
  --type git \
  --actor "attacker-handle" \
  --url "https://github.com/OWNER/REPO/commit/FORCE_PUSHED_SHA.patch" \
  --timestamp "2024-01-15T00:00:00Z" \
  --verification single_source \
  --notes "Commit force-pushed off main branch on 2024-01-16. Recovered via direct fetch."

---

Recovery Failure Modes

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.

---

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)

---

Affected Versions

---

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

---

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

---

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

Malicious Package Investigation Report

---

📦 Package Metadata

• Package Name:
• Registry: [NPM / PyPI / RubyGems / etc.]
• Affected Versions:
• Malicious Version(s):
• Downloads at Time of Detection:
• Package URL:

---

🚩 Indicators of Compromise (IOCs)

• Malicious URL(s):
• Exfiltrated Data Types: [Environment variables, ~/.ssh/id_rsa, /etc/shadow, etc.]
• Exfiltration Method: [DNS tunneling, HTTP POST to C2, etc.]
• C2 IP/Domain:

---

🛠️ Analysis Summary

• Primary Mechanism: [Typosquatting / Dependency Confusion / Maintainer Takeover]
• Behavior Description:
• [Example: Installs a postinstall script that exfiltrates environment variables.]
• [Example: Patches setup.py to download a secondary payload.]

---

🔍 Evidence Registry

---

🛡️ Recommended Mitigations

1. [ ] Unpublish/Report the package to the registry. 2. [ ] Audit package-lock.json or requirements.txt across all projects. 3. [ ] Rotate secrets exfiltrated via environment variables. 4. [ ] Pin specific hashes (SHASUM) for mission-critical dependencies.