oss-forensics-agent

name	oss-forensics-agent
description	GRIMSEC Agent 11: Evidence-backed forensic investigation of open-source GitHub repositories. Use when investigating supply chain incidents, suspicious commits, compromised maintainer accounts, backdoor injections, or any open-source security incident. Triggered by phrases like "investigate this repo", "forensic analysis of", "check for supply chain compromise", "was this package backdoored", "analyze suspicious maintainer activity", "oss forensics", or after cicd-pipeline-auditor flags suspicious patterns. Inspired by Raptor's /oss-forensics command.
license	MIT
metadata	{"author":"GRIMSEC","version":"1.0","suite":"GRIMSEC DevSecOps","agent-number":"11","suite-position":"Runs after cicd-pipeline-auditor; feeds executive-reporting-agent and threat-intel-monitor"}

OSS Forensics Agent

GRIMSEC Agent 11 — Evidence-backed forensic investigation of open-source GitHub repositories.

When to Use This Skill

Load this skill when asked to:

• Investigate a GitHub repository for supply chain compromise
• Analyze suspicious commit history or maintainer behavior
• Determine if a package was backdoored
• Reconstruct the timeline of a security incident
• Assess whether a dependency in inventory.json is compromised
• Follow up on findings from cicd-pipeline-auditor (reads audit-report.json)
• Produce a forensic report for executive escalation

Trigger phrases: "investigate this repo", "was this package compromised", "forensic analysis", "supply chain incident", "suspicious maintainer", "backdoor injection", "oss forensics".

---

Reference Files

Load these references when relevant:

File	When to Load
references/evidence-sources.md	Phase 1 — which APIs/tools to use and how
references/ioc-patterns.md	Phase 2 — what patterns constitute an IOC
references/supply-chain-attacks.md	Phase 2–4 — compare against known attack patterns

---

Inputs

Input	Source	Required
GitHub repo URL	User prompt	Yes
Investigation prompt	User prompt	Yes (e.g., "investigate suspicious maintainer activity")
audit-report.json	cicd-pipeline-auditor output	No (enriches Phase 1)
inventory.json	Dependency inventory	No (scopes Phase 1 to known deps)

---

Pipeline

Input: GitHub repo URL + investigation prompt
  │
  ├─► Phase 1: Evidence Collection
  ├─► Phase 2: IOC Extraction
  ├─► Phase 3: Timeline Reconstruction
  ├─► Phase 4: Hypothesis Formation & Verification
  └─► Phase 5: Forensic Report

---

Phase 1: Evidence Collection

Goal: Gather all available evidence from every available source before forming conclusions.

Script: scripts/collect-evidence.py
Read: references/evidence-sources.md for API endpoints and query patterns.

1a. GitHub REST API v3 + GraphQL v4

Collect the following via GitHub API. Authenticate with GITHUB_TOKEN env var when available.

GET /repos/{owner}/{repo}                          # repo metadata, visibility, fork status
GET /repos/{owner}/{repo}/commits?per_page=100     # recent commit history
GET /repos/{owner}/{repo}/commits/{sha}            # individual commit detail with patch
GET /repos/{owner}/{repo}/pulls?state=all          # all pull requests
GET /repos/{owner}/{repo}/issues?state=all         # issues (may contain incident disclosures)
GET /repos/{owner}/{repo}/releases                 # all releases + assets
GET /repos/{owner}/{repo}/contributors             # contributor list + commit counts
GET /repos/{owner}/{repo}/collaborators            # current collaborators + permissions
GET /repos/{owner}/{repo}/teams                    # teams with access
GET /repos/{owner}/{repo}/hooks                    # webhook configurations
GET /repos/{owner}/{repo}/keys                     # deploy keys
GET /repos/{owner}/{repo}/branches                 # branch list + protection status
GET /repos/{owner}/{repo}/branches/{branch}/protection  # branch protection rules
GET /repos/{owner}/{repo}/actions/workflows        # CI/CD workflow files
GET /repos/{owner}/{repo}/actions/runs?per_page=50 # recent workflow runs
GET /orgs/{org}/audit-log                          # org audit log (requires org owner token)

For GraphQL v4, query contributor history and permission change events not available in REST.

1b. Git History (Local Clone)

Use scripts/analyze-commits.py to perform local clone analysis:

git clone --bare https://github.com/{owner}/{repo}.git repo.git
cd repo.git
git log --all --oneline --format="%H %ae %an %ai %s"   # full history all branches
git log --all --diff-filter=A --name-only               # files added per commit
git log --all --diff-filter=D --name-only               # files deleted per commit
git reflog --all                                        # reflog for force-push detection
git fsck --unreachable                                  # dangling/orphaned commits
git log --format="%H %ae %ce" | awk '$2 != $3'         # author/committer email mismatch
git log --all --format="%H" | xargs -I{} git cat-file -p {} | grep -i "base64\|eval\|exec"

Flag commits where:

• Author email ≠ committer email (rebase / force-push indicators)
• Commit timestamp falls outside maintainer's historical timezone window
• Commit modifies .github/workflows/, package.json#scripts, setup.py, CMakeLists.txt
• Merge commits that bypass PR (no associated PR number in message)

1c. GH Archive (Historical Event Data)

GH Archive records immutable GitHub event data. Use for events before the repo's git history begins or for deleted events.

BigQuery: SELECT * FROM `githubarchive.day.20250101`
          WHERE repo.name = '{owner}/{repo}'
          AND type IN ('PushEvent','PullRequestEvent','MemberEvent',
                       'TeamAddEvent','ReleaseEvent','DeleteEvent',
                       'PublicEvent','ForkEvent','WatchEvent')
          ORDER BY created_at ASC

Also query the GH Archive HTTP API for specific dates:

https://data.gharchive.org/YYYY-MM-DD-{H}.json.gz

Key event types for forensics:

• MemberEvent (action: added/removed) — maintainer permission changes
• TeamAddEvent — team membership changes
• DeleteEvent — branch/tag deletions
• PushEvent with forced: true — force pushes

1d. Wayback Machine

Recover deleted content (READMEs, docs, release notes, package.json versions):

CDX API: https://web.archive.org/cdx/search/cdx?url={github_url}&output=json&fl=timestamp,statuscode,original&limit=200
Fetch:   https://web.archive.org/web/{timestamp}/{original_url}

Targets for Wayback recovery:

• https://github.com/{owner}/{repo}/blob/main/package.json — historical dependency versions
• https://github.com/{owner}/{repo}/blob/main/.github/workflows/*.yml — deleted workflow files
• https://www.npmjs.com/package/{pkg} — historical package page (before unpublish)
• https://pypi.org/project/{pkg}/ — historical PyPI pages

1e. Package Registry APIs

npm:   https://registry.npmjs.org/{package}             # full publish history + dist-tags
       https://registry.npmjs.org/{package}/{version}   # specific version metadata
PyPI:  https://pypi.org/pypi/{package}/json             # release history + file hashes
       https://pypi.org/pypi/{package}/{version}/json
Go:    https://proxy.golang.org/{module}/@v/list        # available versions
       https://sum.golang.org/lookup/{module}@{version} # hash verification

Check for:

• Versions published in quick succession (< 1 hour apart)
• Versions with new maintainer in _npmUser or maintainers array
• Dist-tags moved to a different version than expected
• Checksum mismatches vs known-good versions

1f. Output

Save all raw evidence to forensics/evidence/:

forensics/evidence/
├── github-api-{owner}-{repo}.json
├── commits-{sha-range}.json
├── gh-archive-events.json
├── wayback-snapshots.json
└── registry-{pkg}-history.json

---

Phase 2: IOC Extraction

Goal: Identify Indicators of Compromise from collected evidence.

Read: references/ioc-patterns.md for full pattern library.

IOC Categories

Code Obfuscation IOCs:

• base64_decode, atob(), Buffer.from(x,'base64'), eval(Buffer.from(...)) in source
• Hex-encoded strings: \x68\x74\x74\x70 patterns
• Long one-line minified additions to previously readable files
• exec(), __import__('os').system(), subprocess.run() in non-test code
• Encoded payloads in string literals > 200 chars

Exfiltration IOCs:

• HTTP calls to domains not present in project documentation or previous commits
• DNS exfiltration: constructing domains with environment variable content
• process.env or os.environ values sent in request headers/body/URL
• POST to webhook URLs (Discord, Slack, custom) not in project's legitimate use
• Outbound connections in postinstall, preinstall, prepare scripts

Environment Access IOCs:

• process.env.NPM_TOKEN, process.env.AWS_*, process.env.GH_TOKEN
• os.environ['CI'], os.environ['GITHUB_TOKEN'], os.environ['SECRET_*']
• Reading ~/.ssh/, ~/.aws/credentials, ~/.npmrc, ~/.gitconfig
• Accessing /proc/ filesystem

Install Hook IOCs:

• package.json scripts.postinstall / scripts.preinstall with network calls
• setup.py cmdclass or install_requires with dynamic network fetch
• go generate directives fetching remote content
• CMakeLists.txt ExternalProject_Add pointing to suspicious hosts

Behavioral IOCs:

• New collaborator added < 7 days before a suspicious commit
• Force push to default branch (from git reflog or GH Archive PushEvent.forced)
• Release tag created without an associated merged PR
• Branch protection disabled (GH Archive MemberEvent or audit log)
• Commit author timezone shift > 4 hours from historical average
• Author/committer email mismatch on commits to default branch
• CI workflow modified to curl | bash remote scripts
• Workflow exfiltrating secrets.* to external services
• Workflow checkouts of unreviewed PRs with pull_request_target

IOC Output Format

Save forensics/iocs.json:

{
  "repo": "owner/repo",
  "investigation_date": "ISO-8601",
  "iocs": [
    {
      "id": "IOC-001",
      "category": "code_obfuscation | exfiltration | env_access | install_hook | behavioral",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "description": "Human-readable description",
      "evidence": {
        "source": "github_api | git_log | gh_archive | wayback | registry",
        "commit_sha": "...",
        "file_path": "...",
        "line_numbers": [42, 43],
        "raw_snippet": "...",
        "url": "https://..."
      },
      "first_seen": "ISO-8601",
      "last_seen": "ISO-8601"
    }
  ]
}

---

Phase 3: Timeline Reconstruction

Goal: Build a chronological, correlated event timeline to identify the initial compromise point and attack progression.

Script: scripts/generate-timeline.py

Event Sources to Correlate

1. Git commits — timestamp, author, files changed
2. GitHub API events — collaborator additions, permission changes, branch protection changes
3. GH Archive events — MemberEvent, PushEvent, ReleaseEvent, DeleteEvent
4. Package registry — publish timestamps, maintainer changes
5. Wayback snapshots — when content changed or disappeared
6. Issue/PR timeline — vulnerability disclosures, incident reports

Timeline Construction Rules

• Use UTC timestamps throughout
• Prefer Git commit timestamps but validate against GH Archive (committed-at vs pushed-at)
• Flag any event where the git commit time ≠ push time by > 24 hours (possible backdating)
• Identify the pivot point: the earliest event that represents a departure from normal behavior
• Mark events as: NORMAL, SUSPICIOUS, MALICIOUS, RESPONSE, UNKNOWN

Output

Save forensics/timeline.json:

{
  "repo": "owner/repo",
  "timeline": [
    {
      "timestamp": "ISO-8601",
      "event_type": "commit | pr | release | collaborator_change | branch_protection | force_push | registry_publish | wayback_change",
      "classification": "NORMAL | SUSPICIOUS | MALICIOUS | RESPONSE | UNKNOWN",
      "actor": "github_username or email",
      "summary": "One-line description",
      "ioc_refs": ["IOC-001"],
      "evidence_url": "https://...",
      "raw": {}
    }
  ],
  "pivot_point": "ISO-8601 timestamp of initial compromise",
  "attack_duration_hours": 0
}

---

Phase 4: Hypothesis Formation & Verification

Goal: Form evidence-backed hypotheses about what happened, evaluate each against all evidence, and assign confidence levels. Never assert without evidence.

Hypothesis Types

Consider these hypotheses based on the evidence:

Hypothesis	Key Evidence To Look For
Compromised maintainer account	Account login from new location/IP, new SSH key added, password reset before incident
New malicious maintainer added	MemberEvent close to suspicious commit, new contributor with no prior history
Build system compromise	CI/CD workflow modification, build artifact hash mismatch, Codecov-style injector
Dependency confusion / typosquatting	Package name similar to internal package, unexpected registry source
Malicious PR merged	PR from external contributor with no review, bypass of branch protection
Insider threat / maintainer sabotage	Known maintainer with documented grievance (issues/social media), colors.js-style
Automated bot compromise	Bot token stolen, workflow GITHUB_TOKEN abused

For Each Hypothesis

Structure each hypothesis entry:

{
  "id": "H-001",
  "title": "Compromised maintainer account used to inject backdoor",
  "confidence": "HIGH | MEDIUM | LOW",
  "supporting_evidence": [
    {
      "description": "New SSH deploy key added 2 days before malicious commit",
      "source": "GitHub API /repos/{owner}/{repo}/keys",
      "url": "https://..."
    }
  ],
  "contradicting_evidence": [
    {
      "description": "Commit author GPG key matches maintainer's known signing key",
      "source": "git log --show-signature",
      "url": null
    }
  ],
  "verdict": "One-paragraph assessment"
}

Confidence Rules:

• HIGH: Multiple independent evidence sources corroborate; no significant contradictions
• MEDIUM: Some evidence supports; contradictions or evidence gaps exist
• LOW: Plausible but evidence is circumstantial or single-source

Verify Claims

Before finalizing:

1. Re-fetch any URL cited in evidence to confirm it still exists or note if removed
2. Cross-check commit SHAs between GitHub API and GH Archive
3. Verify package checksums against registry hashes
4. Note any evidence that has been deleted/altered (itself an IOC)

Save: forensics/hypotheses.json

---

Phase 5: Forensic Report

Goal: Produce a complete, evidence-backed forensic report.

Template: assets/templates/forensic-report-template.md

Report Sections

1. Executive Summary — 3–5 sentences: what happened, when, who was affected, severity
2. Repository Profile — owner, stars, dependents, ecosystem role
3. Investigation Scope — date range, sources examined, limitations
4. Timeline — chronological table of key events with classification labels
5. Indicators of Compromise — table with IOC ID, category, severity, description, evidence link
6. Hypotheses — each with confidence, supporting/contradicting evidence, verdict
7. Affected Versions — table of versions: Safe / Malicious / Unverified
8. Impact Assessment — who was affected, what data/secrets at risk
9. Remediation
   • Versions to avoid
   • Safe upgrade path
   • Immediate actions (rotate secrets, audit logs, check for lateral movement)
10. Evidence Inventory — table of all evidence files with sources and retrieval dates
11. Limitations & Caveats — what could not be verified, evidence that was deleted

Save: forensics/forensic-report.md

---

Output Structure

forensics/
├── evidence/
│   ├── github-api-{owner}-{repo}.json
│   ├── commits-{sha-range}.json
│   ├── gh-archive-events.json
│   ├── wayback-snapshots.json
│   └── registry-{pkg}-history.json
├── iocs.json
├── timeline.json
├── hypotheses.json
└── forensic-report.md

---

GRIMSEC Integration

Direction	Agent	Data
Reads from	cicd-pipeline-auditor	audit-report.json — CI/CD findings that may indicate supply chain compromise
Reads from	(dependency scanner)	inventory.json — dependency list to check for known-compromised packages
Writes to	executive-reporting-agent	forensics/forensic-report.md — for incident report generation
Writes to	threat-intel-monitor	forensics/iocs.json — new IOCs to add to monitoring watchlist

Trigger conditions:

• Manual invocation with repo URL
• After cicd-pipeline-auditor flags suspicious workflow modifications
• After threat-intel-monitor identifies a dependency in inventory.json matching a known-compromised package

---

Investigator Rules

1. Evidence first, conclusions second. Never assert a hypothesis without citing evidence.
2. Cite sources. Every claim must include the source (API endpoint, commit SHA, Wayback URL, GH Archive timestamp).
3. Preserve evidence. Save raw API responses before summarizing. Deleted content is itself evidence.
4. Note absence. If expected evidence is missing (e.g., no PR for a release), document that gap.
5. Timestamp everything. All events in UTC. Flag any timezone inconsistencies.
6. Never modify the repo. This is read-only investigation. Clone bare (--bare), never push.
7. Confidence honesty. LOW confidence is better than unfounded HIGH confidence.