mindforge-cc 11.8.2 → 11.9.0

package/.mindforge/skills/osint-investigation/scripts/timing_analysis.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""Permutation test for donation/contract timing correlation (stdlib-only).
+
+For each (donor, vendor) pair, compute the mean number of days between each
+donation and the nearest contract award. Then shuffle contract award dates
+N times within the observation window and compute the same statistic. The
+one-tailed p-value is the fraction of permutations whose mean is <= the
+observed mean (smaller distance = tighter clustering).
+
+Adapted from ShinMegamiBoson/OpenPlanter (MIT). Differences:
+  - Pure stdlib (no pandas / numpy)
+  - Domain-agnostic (no snow-vendor / CRITICAL-politician filter)
+  - Configurable column names via flags
+  - Optional --seed for reproducibility
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import datetime as dt
+import json
+import random
+import statistics
+from collections import defaultdict
+from pathlib import Path
+
+_DATE_FORMATS = ("%Y-%m-%d", "%m/%d/%Y", "%Y/%m/%d", "%m-%d-%Y", "%Y%m%d")
+
+
+def parse_date(raw: str) -> dt.date | None:
+    if not raw:
+        return None
+    raw = raw.strip()
+    for fmt in _DATE_FORMATS:
+        try:
+            return dt.datetime.strptime(raw, fmt).date()
+        except ValueError:
+            continue
+    return None
+
+
+def _read(path: str) -> list[dict[str, str]]:
+    with open(path, newline="", encoding="utf-8") as fh:
+        return list(csv.DictReader(fh))
+
+
+def _nearest_distance(donation_date: dt.date, awards: list[dt.date]) -> int:
+    """Absolute days to nearest award date."""
+    return min(abs((donation_date - a).days) for a in awards)
+
+
+def _permute(
+    awards_count: int,
+    donations: list[dt.date],
+    date_min: dt.date,
+    date_max: dt.date,
+    rng: random.Random,
+) -> float:
+    """One permutation: draw uniform random award dates, compute mean nearest-distance."""
+    span_days = (date_max - date_min).days or 1
+    rand_awards = [
+        date_min + dt.timedelta(days=rng.randint(0, span_days))
+        for _ in range(awards_count)
+    ]
+    distances = [_nearest_distance(d, rand_awards) for d in donations]
+    return statistics.mean(distances)
+
+
+def analyze(
+    donations_path: str,
+    donation_date_col: str,
+    donation_amount_col: str,
+    donation_donor_col: str,
+    donation_recipient_col: str,
+    contracts_path: str,
+    contract_date_col: str,
+    contract_vendor_col: str,
+    cross_links_path: str | None,
+    n_permutations: int = 1000,
+    min_donations: int = 3,
+    p_threshold: float = 0.05,
+    seed: int | None = None,
+    out_path: str = "timing.json",
+) -> dict:
+    rng = random.Random(seed)
+
+    donations = _read(donations_path)
+    contracts = _read(contracts_path)
+
+    # Allow optional join through cross_links — donor (left) ↔ vendor (right).
+    # When present, donor strings get mapped to matched vendor names so the
+    # vendor-date index lookup actually finds the contracts.
+    matched_pairs: set[tuple[str, str]] | None = None
+    donor_to_vendors: dict[str, set[str]] = defaultdict(set)
+    if cross_links_path:
+        matched_pairs = set()
+        for row in _read(cross_links_path):
+            left = row.get("left_name", "")
+            right = row.get("right_name", "")
+            matched_pairs.add((left, right))
+            donor_to_vendors[left].add(right)
+
+    # Index contract dates by vendor name.
+    vendor_to_award_dates: dict[str, list[dt.date]] = defaultdict(list)
+    all_award_dates: list[dt.date] = []
+    for row in contracts:
+        d = parse_date(row.get(contract_date_col, ""))
+        if not d:
+            continue
+        vendor_to_award_dates[row.get(contract_vendor_col, "").strip()].append(d)
+        all_award_dates.append(d)
+
+    if not all_award_dates:
+        raise SystemExit(f"No parseable dates in {contracts_path}/{contract_date_col}")
+    global_min = min(all_award_dates)
+    global_max = max(all_award_dates)
+
+    # Group donations by (donor, recipient).
+    grouped: dict[tuple[str, str], list[tuple[dt.date, float]]] = defaultdict(list)
+    for row in donations:
+        donor = row.get(donation_donor_col, "").strip()
+        recip = row.get(donation_recipient_col, "").strip()
+        d = parse_date(row.get(donation_date_col, ""))
+        try:
+            amt = float(row.get(donation_amount_col, "0") or 0)
+        except ValueError:
+            amt = 0.0
+        if not (donor and recip and d):
+            continue
+        grouped[(donor, recip)].append((d, amt))
+
+    results = []
+    skipped = 0
+    for (donor, recip), records in grouped.items():
+        if len(records) < min_donations:
+            skipped += 1
+            continue
+        # Only test if donor appears in cross-links (when provided). The
+        # (donor, candidate) tuple itself is NOT what's in matched_pairs —
+        # cross_links pairs are (donor, vendor). We use the cross-link to
+        # map donor → vendor name(s) so the vendor-date index resolves.
+        if matched_pairs is not None and donor not in donor_to_vendors:
+            skipped += 1
+            continue
+        # Try direct donor→awards first, then go through cross-link vendor names.
+        award_dates = list(vendor_to_award_dates.get(donor, []))
+        if not award_dates:
+            award_dates = list(vendor_to_award_dates.get(recip, []))
+        if not award_dates and donor_to_vendors.get(donor):
+            for vendor_name in donor_to_vendors[donor]:
+                award_dates.extend(vendor_to_award_dates.get(vendor_name, []))
+        if not award_dates:
+            skipped += 1
+            continue
+
+        donation_dates = [d for (d, _) in records]
+        observed = statistics.mean(
+            _nearest_distance(d, award_dates) for d in donation_dates
+        )
+
+        permuted_means = [
+            _permute(len(award_dates), donation_dates, global_min, global_max, rng)
+            for _ in range(n_permutations)
+        ]
+        p_value = sum(1 for m in permuted_means if m <= observed) / n_permutations
+        null_mean = statistics.mean(permuted_means)
+        null_std = statistics.pstdev(permuted_means) or 1.0
+        effect_size = (null_mean - observed) / null_std
+
+        results.append(
+            {
+                "donor": donor,
+                "recipient": recip,
+                "n_donations": len(records),
+                "n_award_dates": len(award_dates),
+                "observed_mean_days": round(observed, 2),
+                "null_mean_days": round(null_mean, 2),
+                "p_value": round(p_value, 4),
+                "effect_size_sd": round(effect_size, 2),
+                "significant": p_value < p_threshold,
+                "total_donation_amount": round(sum(a for (_, a) in records), 2),
+            }
+        )
+
+    results.sort(key=lambda r: r["p_value"])
+
+    payload = {
+        "metadata": {
+            "n_permutations": n_permutations,
+            "min_donations": min_donations,
+            "p_threshold": p_threshold,
+            "seed": seed,
+            "n_pairs_tested": len(results),
+            "n_pairs_skipped": skipped,
+            "n_significant": sum(1 for r in results if r["significant"]),
+            "observation_window": [global_min.isoformat(), global_max.isoformat()],
+        },
+        "results": results,
+    }
+
+    Path(out_path).write_text(json.dumps(payload, indent=2))
+    return payload
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--donations", required=True)
+    p.add_argument("--donation-date-col", required=True)
+    p.add_argument("--donation-amount-col", required=True)
+    p.add_argument("--donation-donor-col", required=True)
+    p.add_argument("--donation-recipient-col", required=True)
+    p.add_argument("--contracts", required=True)
+    p.add_argument("--contract-date-col", required=True)
+    p.add_argument("--contract-vendor-col", required=True)
+    p.add_argument(
+        "--cross-links",
+        help="Optional cross_links.csv to restrict (donor, vendor) pairs",
+    )
+    p.add_argument("--permutations", type=int, default=1000)
+    p.add_argument("--min-donations", type=int, default=3)
+    p.add_argument("--p-threshold", type=float, default=0.05)
+    p.add_argument("--seed", type=int)
+    p.add_argument("--out", default="timing.json")
+    a = p.parse_args()
+
+    payload = analyze(
+        donations_path=a.donations,
+        donation_date_col=a.donation_date_col,
+        donation_amount_col=a.donation_amount_col,
+        donation_donor_col=a.donation_donor_col,
+        donation_recipient_col=a.donation_recipient_col,
+        contracts_path=a.contracts,
+        contract_date_col=a.contract_date_col,
+        contract_vendor_col=a.contract_vendor_col,
+        cross_links_path=a.cross_links,
+        n_permutations=a.permutations,
+        min_donations=a.min_donations,
+        p_threshold=a.p_threshold,
+        seed=a.seed,
+        out_path=a.out,
+    )
+    meta = payload["metadata"]
+    print(
+        f"Tested {meta['n_pairs_tested']} pairs ({meta['n_pairs_skipped']} skipped). "
+        f"Significant (p<{meta['p_threshold']}): {meta['n_significant']}. "
+        f"Wrote {a.out}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.mindforge/skills/osint-investigation/templates/source-template.md

@@ -0,0 +1,59 @@
+# <Source Name>
+
+## 1. Summary
+
+What this data source is, who publishes it, why it matters for investigations.
+
+## 2. Access Methods
+
+- API endpoint(s)
+- Bulk download URLs
+- Auth requirements (none / API key / OAuth)
+- Rate limits
+
+## 3. Data Schema
+
+Key fields, record types, table relationships. List the columns the fetch
+script emits.
+
+## 4. Coverage
+
+- Jurisdiction
+- Time range
+- Update frequency
+- Data volume (rows / GB)
+
+## 5. Cross-Reference Potential
+
+Which other sources can be joined and on what keys. Be explicit:
+
+- `<source>` ↔ `<column>` (join key: <normalized entity name / EIN / CIK / etc.>)
+
+## 6. Data Quality
+
+Known issues — formatting inconsistencies, missing fields, duplicates,
+historical gaps, redaction.
+
+## 7. Acquisition Script
+
+Path: `scripts/fetch_<source>.py`
+
+Example:
+
+```bash
+python3 SKILL_DIR/scripts/fetch_<source>.py --<filter> <value> --out data/<source>.csv
+```
+
+Output CSV columns: `<col1>, <col2>, ...`
+
+## 8. Legal & Licensing
+
+- Public records law / FOIA basis
+- Terms of use / acceptable use
+- Attribution requirements (if any)
+
+## 9. References
+
+- Official docs: <url>
+- Data dictionary: <url>
+- Related coverage / journalism: <url>

package/.mindforge/skills/oss-forensics/SKILL.md

@@ -26,7 +26,7 @@ Read these before every investigation step. Violating them invalidates the repor
 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.
+7. **Suspicious Code Rule**: Never run code found inside the investigated repository locally. Analyze statically only, or use `Bash` 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.
 
 ---
@@ -41,7 +41,7 @@ Read these before every investigation step. Violating them invalidates the repor
 
 > **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/`
+> resolve `SKILL_DIR` to the actual path — e.g. `~/.mindforge/skills/oss-forensics/`
 > or the `optional-skills/` equivalent. All script and template references are relative to it.
 
 ## Phase 0: Initialization
@@ -76,7 +76,7 @@ Read these before every investigation step. Violating them invalidates the repor
   - 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.
+**Tools**: Reasoning only, or `Bash` 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)
@@ -89,7 +89,7 @@ Read these before every investigation step. Violating them invalidates the repor
 
 ## 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.
+Spawn up to 5 specialist investigator sub-agents using `Agent` (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.
 
@@ -265,7 +265,7 @@ LIMIT 200
 
 **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 domain/IP: check passive DNS, WHOIS records (via `WebFetch` 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))
@@ -302,7 +302,7 @@ A hypothesis must:
 - 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.
+For each hypothesis, spawn a `Agent` sub-agent to attempt to find disconfirming evidence before confirming.
 
 ---
 

package/.mindforge/skills/oss-forensics/references/evidence-types.md

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

package/.mindforge/skills/oss-forensics/references/github-archive-guide.md

@@ -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 the agent
+
+**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.