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,89 @@
|
|||
# Evidence Types Reference
|
||||
|
||||
Taxonomy of all evidence types, IOC types, GitHub event types, and observation types
|
||||
used in OSS forensic investigations.
|
||||
|
||||
---
|
||||
|
||||
## Evidence Source Types
|
||||
|
||||
| Type | Description | Example Sources |
|
||||
|------|-------------|-----------------|
|
||||
| `git` | Data from local git repository analysis | `git log`, `git fsck`, `git reflog`, `git blame` |
|
||||
| `gh_api` | Data from GitHub REST API responses | `/repos/.../commits`, `/repos/.../pulls`, `/repos/.../events` |
|
||||
| `gh_archive` | Data from GitHub Archive (BigQuery) | `githubarchive.month.*` BigQuery tables |
|
||||
| `web_archive` | Archived web pages from Wayback Machine | CDX API results, `web.archive.org/web/...` snapshots |
|
||||
| `ioc` | Indicator of Compromise from any source | Extracted from vendor reports, git history, network traces |
|
||||
| `analysis` | Derived insight from cross-source correlation | "SHA present in archive but absent from API" |
|
||||
| `vendor_report` | External security vendor or researcher report | CVE advisories, blog posts, NVD records |
|
||||
| `manual` | Manually recorded observation by investigator | Notes on behavioral patterns, timeline gaps |
|
||||
|
||||
---
|
||||
|
||||
## IOC Types
|
||||
|
||||
| Type | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| `COMMIT_SHA` | A git commit hash linked to malicious activity | `abc123def456...` |
|
||||
| `FILE_PATH` | A suspicious file inside the repository | `src/utils/crypto.js`, `dist/index.min.js` |
|
||||
| `API_KEY` | An API key accidentally committed | `AKIA...` (AWS), `ghp_...` (GitHub PAT) |
|
||||
| `SECRET` | A generic secret / credential | Database password, private key blob |
|
||||
| `IP_ADDRESS` | A C2 server or attacker IP | `192.0.2.1` |
|
||||
| `DOMAIN` | A malicious or suspicious domain | `evil-cdn.io`, typosquatted package registry domain |
|
||||
| `PACKAGE_NAME` | A malicious or squatted package name | `colo-rs` (typosquatting `color`), `lodash-utils` |
|
||||
| `ACTOR_USERNAME` | A GitHub handle linked to the attack | `malicious-bot-account` |
|
||||
| `MALICIOUS_URL` | A URL to a malicious resource | `https://evil.example.com/payload.sh` |
|
||||
| `WORKFLOW_FILE` | A suspicious CI/CD workflow file | `.github/workflows/release.yml` |
|
||||
| `BRANCH_NAME` | A suspicious branch | `refs/heads/temp-fix-do-not-merge` |
|
||||
| `TAG_NAME` | A suspicious git tag | `v1.0.0-security-patch` |
|
||||
| `RELEASE_NAME` | A suspicious release | Release with no associated tag or changelog |
|
||||
| `OTHER` | Catch-all for unclassified IOCs | — |
|
||||
|
||||
---
|
||||
|
||||
## GitHub Archive Event Types (12 Types)
|
||||
|
||||
| Event Type | Forensic Relevance |
|
||||
|------------|-------------------|
|
||||
| `PushEvent` | Core: `payload.distinct_size=0` with `payload.size>0` → force push. `payload.before`/`payload.head` shows rewritten history. |
|
||||
| `PullRequestEvent` | Detects deleted PRs, rapid open→close patterns, PRs from new accounts |
|
||||
| `IssueEvent` | Detects deleted issues, coordinated labeling, rapid closure of vulnerability reports |
|
||||
| `IssueCommentEvent` | Deleted comments, rapid activity bursts |
|
||||
| `WatchEvent` | Star-farming campaigns (coordinated starring from new accounts) |
|
||||
| `ForkEvent` | Unusual fork patterns before malicious commit |
|
||||
| `CreateEvent` | Branch/tag creation: signals new release or code injection point |
|
||||
| `DeleteEvent` | Branch/tag deletion: critical — often used to hide traces |
|
||||
| `ReleaseEvent` | Unauthorized releases, release artifacts modified post-publish |
|
||||
| `MemberEvent` | Collaborator added/removed: maintainer compromise indicator |
|
||||
| `PublicEvent` | Repository made public (sometimes to drop malicious code briefly) |
|
||||
| `WorkflowRunEvent` | CI/CD pipeline executions: workflow injection, secret exfiltration |
|
||||
|
||||
---
|
||||
|
||||
## Evidence Verification States
|
||||
|
||||
| State | Meaning |
|
||||
|-------|---------|
|
||||
| `unverified` | Collected from a single source, not cross-referenced |
|
||||
| `single_source` | The primary source has been confirmed directly (e.g., SHA resolves on GitHub), but no second source |
|
||||
| `multi_source_verified` | Confirmed from 2+ independent sources (e.g., GH Archive AND GitHub API both show the same event) |
|
||||
|
||||
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)
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `CommitObservation` | Specific commit SHA with metadata (author, date, files changed) |
|
||||
| `ForceWashObservation` | Evidence that commits were force-erased from a branch |
|
||||
| `DanglingCommitObservation` | SHA present in git object store but unreachable from any ref |
|
||||
| `IssueObservation` | A GitHub issue (current or archived) with title, body, timestamp |
|
||||
| `PRObservation` | A GitHub PR (current or archived) with diff summary, reviewers |
|
||||
| `IOC` | A single Indicator of Compromise with context |
|
||||
| `TimelineGap` | A period with unusual absence of expected activity |
|
||||
| `ActorAnomalyObservation` | Behavioral anomaly for a specific GitHub actor |
|
||||
| `WorkflowAnomalyObservation` | Suspicious CI/CD workflow change or unexpected run |
|
||||
| `CrossSourceDiscrepancy` | Item present in one source but absent in another (strong deletion indicator) |
|
||||
|
|
@ -0,0 +1,184 @@
|
|||
# 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
|
||||
|
||||
| Event Type | What It Records | Forensic Value |
|
||||
|------------|-----------------|----------------|
|
||||
| `PushEvent` | Commits pushed to a branch | Force-push detection, commit timeline, author attribution |
|
||||
| `PullRequestEvent` | PR opened, closed, merged, reopened | Deleted PR recovery, review timeline |
|
||||
| `IssuesEvent` | Issue opened, closed, reopened, labeled | Deleted issue recovery, social engineering traces |
|
||||
| `IssueCommentEvent` | Comments on issues and PRs | Deleted comment recovery, communication patterns |
|
||||
| `CreateEvent` | Branch, tag, or repository creation | Suspicious branch creation, tag timing |
|
||||
| `DeleteEvent` | Branch or tag deletion | Evidence of cleanup after compromise |
|
||||
| `MemberEvent` | Collaborator added or removed | Permission changes, access escalation |
|
||||
| `PublicEvent` | Repository made public | Accidental exposure of private repos |
|
||||
| `WatchEvent` | User stars a repository | Actor reconnaissance patterns |
|
||||
| `ForkEvent` | Repository forked | Exfiltration of code before cleanup |
|
||||
| `ReleaseEvent` | Release published, edited, deleted | Malicious release injection, deleted release recovery |
|
||||
| `WorkflowRunEvent` | GitHub Actions workflow triggered | CI/CD abuse, unauthorized workflow runs |
|
||||
|
||||
---
|
||||
|
||||
## Query Templates
|
||||
|
||||
### Basic: All Events for a Repository
|
||||
|
||||
```sql
|
||||
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)
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
```sql
|
||||
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)
|
||||
```bash
|
||||
bq query --use_legacy_sql=false --format=json "YOUR QUERY"
|
||||
```
|
||||
|
||||
**Option B: Python** (via `execute_code`)
|
||||
```python
|
||||
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.
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
# 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
|
||||
|
|
@ -0,0 +1,164 @@
|
|||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```sql
|
||||
-- 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
| Failure | Cause | Workaround |
|
||||
|---------|-------|------------|
|
||||
| `git fetch origin SHA` returns "not our ref" | GitHub GC already ran | Try Method 1/2, search Wayback Machine |
|
||||
| `github.com/OWNER/REPO/commit/SHA` returns 404 | GC ran or SHA is wrong | Verify SHA via GH Archive; try partial SHA search |
|
||||
| Wayback Machine has no snapshots | Page was never crawled by IA | Check `commoncrawl.org`, check Google Cache |
|
||||
| BigQuery shows event but no content | GH Archive stores event metadata, not file contents | Recovery only reveals the event occurred, not the content |
|
||||
Loading…
Add table
Add a link
Reference in a new issue