Skip to content

Back to the catalog

SpecterOps/Blacklight — local AI agent attack surface mapping toolkit
github.comrepo

SpecterOps/Blacklight — local AI agent attack surface mapping toolkit

Blacklight is a SpecterOps toolkit for endpoint forensics on AI coding agents, split into Scout (bounded metadata/filesystem triage across Codex, Claude Code, Cursor, Antigravity CLI, and Grok that finds candidate session artifacts without reading their contents) and Session Analysis (a Python CLI that parses selected JSONL/SQLite session downloads from Codex, Claude Code, Cursor, and Antigravity CLI into ranked, redacted local reports). It's built for investigators who need to identify and review AI agent session history on a host — surfacing config, auth metadata, and high-value indicators — while explicitly leaving secret scanning to external tooling; paths are informed by SpecterOps' Endpoint AI Agent Abuse (EAA) technique catalog.

TL;DR SpecterOps' Blacklight scouts and analyzes AI coding agent (Codex, Claude Code, Cursor, Antigravity CLI, Grok) session artifacts on endpoints for forensic triage and redacted reporting.
Open original ↗
Document

What it is

Blacklight is a two-phase toolkit. Scout does bounded endpoint triage (finds candidate session artifacts by metadata without reading their bodies); Session Analysis is a Python CLI (blacklight) that parses selected downloaded artifacts into ranked, redacted reports. The intended flow is Scout → selectively download → analyze — but Scout output is not a prerequisite: any local directory containing recognized-schema JSONL/SQLite files can be analyzed, even if files are flat, nested, renamed, or duplicated.

What to do

Build Scout per platform:

.\blacklight-scout\build.ps1
./blacklight-scout/build.sh
make -C blacklight-scout release-macos

Products land in out/build/scout/. BOF and POSIX libraries take no filters; only Windows executables support tool filtering:

ai_path_scout-windows-x64.exe --include-tool codex
ai_path_scout-managed.exe --include-tool cursor

Install the CLI (requires Python 3.11+); if blacklight isn't on PATH use python3.11 -m blacklight:

python3.11 -m pip install -e .

Run against a directory of collected artifacts:

blacklight sessions ~/Downloads/HOST-001 \
  --run-id HOST-001 \
  --output-directory out/results/HOST-001/reports \
  --max-files 10000

Scope with --include, --exclude, --max-files, --max-file-size; add --json for a machine-readable terminal summary. Use --tool <codex|claude|cursor|antigravity_cli> only to resolve ambiguous evidence, not routinely. Each run emits <RUN_ID>_Session_Report.json and a matching .txt containing parse health, ranked sessions, activity/response-capture metrics, redacted high-value-indicator metadata, and exact source paths.

Caveats

  • Grok is Scout-only. Session Analysis does not parse Grok artifacts in this release — use Scout and Rules for metadata-only Grok recon; don't expect blacklight sessions to handle Grok files.
  • Blacklight runs no secret scanners; hand the reported source paths to your own approved workflow.
  • A file-limit result means discovery was intentionally bounded — it does not stop supported files from being analyzed. Review partial, unsupported, ambiguous, and failed records in the report inventory.
  • Scout ranks by newest activity and size and reports recognized artifact volume; use that total to decide whether to collect more before analyzing.

Technologies named here

Techniques named here

  • Endpoint triage / candidate session artifact discovery
  • Selective artifact collection
  • Redacted session report generation
  • Metadata-only reconnaissance for unsupported artifact types

Related in Blue Team & Detection