blacklight - The future is Mythos-class agents that take vuln-t

项目说明

<di="center">

blacklight

Defenders run grep. Attackers run agents. bl is the counter.

A portable bash CLI that puts an agent on the same Linux defensi you already run.
Observe · Decide · Act · At fleet scale.

<a href=" src=" alt="blacklight.rfxn.com"></a>

![]()

Install · Try it · Architecture · Why this stack · Safety · Roadmap

</div>

> [!IMPORTANT]
> v0.7.0 build, originally written April 2026.
> Production-shape, not production-tested at fleet scale. External operator beta is roadmap P1.
> The full docs site at blacklight.rfxn.com is the richer surface: this README, design notes, recorded trace, and operator collateral, all rendered with proper na.

---

<p align="center">
<strong><em>The agent doesn't belong in a chat window.<br/>
It belongs in the shell, on the host, holding the case across days,<br/>
acting on the substrate the defender already runs.</em></strong>
</p>

---

What blacklight does

At 03:42 UTC on a Saturday, the APSB25-94 ad drops: Magento stores are actively backdoored via a double-extension webshell hidden in the media cache. Eight hours later the on-call team has run grep, find, ModSec audit scrapes, ClamA, APF drops, and crontab audits across forty hosts, by hand.

blacklight collapses that arc into agentic-minutes on the same Linux substrate you already run. The agent in the shell, not the chat. A Managed Agent curator holds the case across days; the wrapper observes, gates, and acts on the host. No platform buy-in. No fleet migration. No analyst retraining.

The power is the act, not the chat. bl defend pushes a ModSec rule with apachectl -t pre-flight and a backup. bl defend firewall drops an attacker IP across APF / CSF / iptables / nftables, CDN-safelist aware, with a TTL retire timer. bl defend sig appends an FP-gated signature to LMD / ClamAV. bl clean quarantines a webshell, removes a poisoned cron, kills a beacon process, with diff and undo. Same operator , on the same hosts, now agent-directed at fleet pace.

---

Install

Floor: bash 4.1+, curl, jq. RPM and DEB packaging under pkg/. bl setup is one-time per Anthropic workspace; see docs/setup-flow.md.

---

Try it: APSB25-94 in fi

> [!NOTE]
> Output is illustrati by the public APSB25-94 ad. The full recorded trace lives at tests/li/; regenerate with make li (requires ANTHROPIC_API_KEY).

1. Collect Apache logs and check the filesystem:

2. Open a case; the curator proposes the next step:

3. Apply the rule (tier-gated, apachectl configtest pre-flight, backup written):

The full motion (obser → consult → defense → clean → case close) is exercised end-to-end by tests/li.bats.

---

yourself

An operator can install + smoke + in under 60 seconds without an Anthropic API key:

| Suite | Command | Co |
|---|---|---|
| Inner-loop | make -C tests test-quick | 00-smoke + 01-cli-surface (~70s) |
| Pre-commit | make -C tests test + make -C tests test-rocky9 | 404 BATS, fixture-driven |
| Release | make -C tests test-all | 6-distro matrix (debian12, rocky9, ubuntu2404, centos7, rocky8, ubuntu2004) |
| Live API | make li | BL_LIVE-gated; requires ANTHROPIC_API_KEY |

> [!TIP]
> The test suite ne a live API call. tests/helpers/curator-mock.bash shims curl against tests/fixtures/step-*.json. Anyone without an API key can run the full 404-test suite.

---

Why this exists: APSB25-94 in production

In mid-March 2026, Sansec publicly disclosed PolyShell as part of APSB25-94, an unauthenticated file-upload RCE affecting every of Magento 2 Community Edition and Adobe Commerce. No patch existed at disclosure. None exists today. Mass exploitation began within 48 hours.

We ran the response across a managed-Magento hosting fleet of a thousand-plus servers. The shape of what hit, drawn from public field reporting on the campaign:

Polyglot signatures had been flagging the artifacts since late February: PHP hidden inside valid GIF and PNG images, shells on disk that looked harmless to every file-type check. Some layers held. Some didn't. Attackers found e paths that bypassed initial WAF mitigations, and we iterated rules through the persistent attack window. We built 50+ assessment checks per store mid-incident because existing tools didn't give us the co the threat demanded. After the industry-wide persistent attack pattern, attack dropped 99.9%, while the rest of the industry continued to wait for a patch that still does not exist.

Where Claude entered. Through that window, Claude was central to keeping pace. Every analyst was pasting e into chat, getting forensic synthesis back, and applying the result by hand. The lesson by the end of the campaign was not "AI helps with IR." The lesson was: the agent doesn't belong in a chat window. It belongs in the shell, on the host, holding the case across days and acting on the substrate the defender already runs. blacklight is that lesson shipped: the agent-directed CLI we wished we'd had on day 1.

> [!NOTE]
> Authored from the experience of responding to APSB25-94 and the alarming pace of incidents like it through the last year: unauthenticated RCEs without patches, polyglot webshells past file-type checks, e outpacing remediation. blacklight is that response, distilled so other defenders can run it from minute one. Corpus in exhibits/fleet-01/ rebuilds APSB25-94 from public sources only (Adobe ad, Sansec analyses, OWASP CRS, Magento docs). No customer data, no internal IOCs.

---

Who this is for

Most defensi are not on Charlotte. They are running ModSecurity, Apache, iptables, nftables, ClamA, syslog, cron (the OSS Linux defensi the industry has built since 2002), and they do not have an enterprise EDR contract, a dedicated security team, or runway for a multi-quarter platform rollout. blacklight is the agentic-defensi for that audience: drop in over an existing stack, plug in an Anthropic API key, and the operator has a curator-driven case desk on the same hosts they already maintain. The art of the possible, at the edge of what is possible, in bash, today.

| Operator profile | What bl gives them |
|---|---|
| L1 SOC analyst at a managed hosting provider or MSP | bl trigger <hit> opens a case from any post-scan hook; the curator dri, defense, and cleanup. The L1 confirms tier-gated steps. |
| Sysadmin / DevOps without dedicated security headcount | The agent IS the security team for the case. No SIEM, no SOAR, no extra analysts. One key, one bash file, one curator session resumable for 30 days. |
| L2 engineer running open Linux infrastructure | One curator session per case, resumable for 30 days. New e attaches via the Files API; the curator extends the hypothesis instead of restarting. |
| Hosting product owner / sysadmin on small fleets | GPL v2, zero license cost, single bash file, $ANTHROPIC_API_KEY is the only credential. Operator pays Anthropic API usage; that is the entire cost. |
| Defender already running rfxn tools (LMD/APF/BFD) | First-class trigger adapter for LMD post_scan_hook; same install discipline and operator as the existing rfxn portfolio. |

bl does not require LMD/APF/BFD. It directs whate primitives the host already has: Apache + ModSec, iptables, nftables, ClamAV, YARA, cron, journalctl. rfxn is one anchor case, not a precondition.

---

How blacklight compares

The first wave of agentic defensi, including CrowdStrike Charlotte AI (Falcon EDR/XDR), Microsoft Security Copilot (Sentinel + Defender + M365 E5), Palo Alto Purple AI (Cortex), and Google SecLM / Duet for Security (Chronicle), shares one structural constraint: the operator must be inside the platform before the agent is a. The reasoning quality is real. The bottleneck is platform reach.

| Adoption barrier | Charlotte-class | blacklight |
|---|---|---|
| Platform onboarding | 3–18 months fleetwide | ~30 seconds (curl \| bash, then bl setup) |
| Per-endpoint licensing | $75–$250 / host / year | $0; only Anthropic API usage |
| SIEM/SOAR/IdP integration | Quarters of platform engineering | None; bl reads existing logs in place |
| Analyst retraining | Weeks to months on DSL | Zero; operator preserved |
| Extensibility | DSL detection authoring | Fork the repo; drop in a markdown skill |
| Lock-in | Per-; migration cost compounds | None; wrapper and skills are GPL v2 |
| Works on CentOS 6 / RHEL 7 / Debian 10 | Rarely supported | Yes; bash 4.1 + curl is the floor |
| Compatible with $10/month customer margins | No | Yes |
| Auditable in 30 minutes | No (closed platform) | Yes (single bash file + markdown) |

Most defenders sit outside the EDR/XDR perimeter, running the OSS Linux defensi on the order of hundreds of millions of hosts Charlotte structurally cannot reach, working harder than they should because platform-bound tooling does not deploy where they li is the counter for that gap: agentic defense on the substrate the defender already owns, with the floor at bash 4.1 and the ceiling at Opus 4.7. Full positioning in PRD.md §10.

---

Architecture

Three layers, clear separation of concerns:

Layer-boundary in. Layer A executes; Layer B reasons; Layer C is untouched by blacklight source: no new rule engines, no new manifests, no new wire formats. Cases are agent-directed REPLs, not batch dossier analyses.

In flow (async polled step-emit). The wrapper does not hold an SSE socket; the agent writes proposed step JSON to bl-case/<case>/pending/<step-id>.json and the wrapper polls.

Polling makes the case memory the self-documenting audit log, keeps bl short-lived per in, and absorbs agent latency in. Full mechanical detail and the Managed Agents primitive map: DESIGN.md §3–§4.

---

Command surface

Nine namespaces, one assembled bash binary. Per-verb help bypasses preflight (bl <verb> --help works on an unseeded workspace).

| Namespace | Purpose |
|---|---|
| bl observe | Read-only e: file, log {apache\|modsec\|journal}, cron, proc, htaccess, fs, firewall, sigs, substrate, bundle. JSONL out. |
| bl consult | Open or attach an in case via the bl-curator Managed Agent. |
| bl run | Execute an agent-prescribed step. Schema-, tier-gated, ledger-logged. --list, --batch [--max <N>], --dry-run, --explain. |
| bl defend | Apply an agent-authored payload: modsec (rule apply / --remove / rollback), firewall (APF/CSF/iptables/nftables, CDN-safelist aware, --retire <duration>), sig (LMD/ClamA, FP-corpus gated). |
| bl clean | Diff-shown remediation: file (quarantine, ne), htaccess, cron, proc (capture-then-SIGTERM). --undo, --unquarantine round-trip. |
| bl case | Lifecycle: show, list, log [--audit], close, reopen. |
| bl setup | Workspace bootstrap: --sync, --reset --force, --gc, --eval, --check, --install-hook lmd, --import-from-lmd. |
| bl trigger | Hook-driven case open. Today: LMD post_scan_hook. |
| bl flush | --outbox drains durable outbox of queued memstore writes (cron-driven); --session-events [--case <id>] syncs new curator report_step calls into memstore pending/ so bl run can dispatch them. |

Ten documented exit codes (docs/exit-codes.md); 1–63 reserved for POSIX, 64–72 for blacklight semantics.

---

Why this stack

Managed Agents: the case IS the session

The curator is an Anthropic Managed Agent, not a stateless API call wrapped in a prompt. Open a case Monday, collect more e Tuesday, call bl consult again Friday; the curator already holds the hypothesis, the e index, the pending steps, and every prior re. No re-prompt, no context reconstruction.

bl setup pro the full fi Managed Agents surface and persists every ID into a single state.json:

Pre-flight (apachectl -t) runs in the agent's own sandbox before any rule promotes to pending/. Skills mount as platform-routed Skills; edits propagate to the next session without code deploy. Workspace-scoped commercially: per-tenant isolation is platform-nati does zero multi-tenant engineering.

Live API surfaces against the managed-agents-2026-04-01 beta header: POST /v1/agents/<id> (update), POST /v1/agents/<id>/archive (retire), sessions.create body { agent: <id>, ... }. See docs/managed-agents.md.

Opus 4.7 + 1M context: full-bundle correlation

A realistic APSB25-94-shaped case routinely accumulates 250,000 to 400,000 tokens of raw e (Apache transfer + error, ModSec audit, FS mtime, crontabs, process snapshots, journalctl, maldet history) before the curator has authored a single hypothesis. Chunking destroys correlation: a retrie "top 5 e items" misses the one record that matters precisely because it does not look relevant in isolation.

The 1M context window makes full-bundle correlation possible without a retrie. Opus 4.7 brings the forensic reasoning depth to distinguish a staging artifact from a false positive by applying ModSecurity grammar, Magento path con, and attacker TTPs simultaneously. A hot mid-in case lives at ~85K–120K tokens (8–12% of the window). Prompt caching amortizes the stable portion (skills + history); only the new e delta is uncached. exhibits/fleet-01/ ships a deterministic, byte-identical, ~360k-token APSB25-94 forensic bundle for stress .

Three-tier model routing

| Surface | Model | Why |
|---|---|---|
| Curator (per-case session) | claude-opus-4-7 | 1M context absorbs full case state without a retriever. Calibrated hypothesis re is the trained behaviour. |
| synthesize_defense / reconstruct_intent | claude-opus-4-7 | Multi-artifact consistency (rule + exception list + ) and multi-layer deobfuscation (base64 → gzinflate → eval). |
| bl obser summary render | claude-sonnet-4-6 | Pattern condensation at speed and cost. Falls back to deterministic helper on --no-llm-summary or BL_DISABLE_LLM=1. |
| FP-gate adjudication (sig append) | claude-haiku-4-5 | Binary-scan-passed signatures spot-checked before LMD/ClamA. Cheap, fast, schema-output. |

Curator calls are infrequent and expensive by design: they carry the full e bundle. Step-execution and FP-gating calls are frequent and cheap by design. Same model e would either make in prohibitively expensive or leave the reasoning-intensi step under-resourced. BL_DISABLE_LLM=1 short-circuits all LLM calls and forces deterministic fallbacks.

Bash, the moat

The bash 4.1 + curl + jq runtime IS the commercial moat against Charlotte-class platforms, because Charlotte cannot deploy here either.

---

Safety model: fi, eight mechanics

Every action is classified into one of fi; the wrapper enforces the gate based on the tier the agent declared, not on trust from the agent alone.

| Tier | Examples | Gate |
|---|---|---|
| read-only | observe.*, consult | Auto-execute, ledger entry only. |
| auto (re, low-risk) | defend.firewall <new-ip>, defend.sig (FP-gate passed) | Auto-execute + notification + 15-min veto window. |
| suggested (re, high-impact) | defend.modsec (new rule) | Operator confirmation required; --yes permitted at this tier. |
| destructive | clean.*, defend.modsec --remove, case.close | Diff shown; --unsafe AND --yes both required. Backup or quarantine entry written before the operation runs. |
| unknown | Anything that does not map to a known verb | Deny by default. Exit 68 (TIER_GATE_DENIED). |

Layered mechanics: schema (schemas/step.json, both platform and wrapper), prompt-injection fence (session-unique token; injection routes to open-questions.md), backup-before-apply (/var/lib/bl/quarantine/), quarantine-not-delete, CDN-safelist-aware firewall, FP corpus gate (deterministic scan + Haiku 4.5 spot-check), append-only ledger under flock FD 200, durable outbox (memstore retries via bl flush).

Full safety policy: docs/security-model.md, docs/action-tiers.md.

---

Skills bundle

Operator-voice knowledge is the moat. The bundle is grounded in twenty-fi of Linux hosting security operations, authored from public sources only (Adobe ad, ModSecurity grammar, Magento de docs, Linux hosting-stack documentation, public YARA repositories), ne data.

| Surface | Path | Count | Role |
|---|---|---|---|
| Raw research substrate | skills/ | 23 dirs / 73 files | Operator-voice knowledge files, grounded in li |
| Routing-skills | routing-skills/ | 6 bundles | Platform Skills primitives when workspace is allowlisted; uploaded as workspace Files in the submitted build |
| Workspace corpora | skills-corpus/ | 8 markdown corpora | Mounted as Files at session create; always present |

Routing model: the legacy bl-skills memory store is retired. Routing-skills upload as Skills primitives when the workspace is allowlisted for /v1/skills; in the submitted build, Anthropic's Skills endpoint is allowlist-gated for this workspace, so the bundles upload through the Files surface instead. The architectural shape (description-routed selection, per-turn lazy load) is the upgrade path once allowlist propagates; the file-fallback is feature-equi at the corpus level and degrades only the per-turn token bound.

Authoring discipline (non-negotiable): each skill opens with a scenario from li, states a non-obvious rule, gives one concrete example drawn from public APSB25-94 material, and names a failure mode. If the only a draft would be generic IR/SOC boilerplate, the gap is flagged and the file lands later. Slop is not shipped.

Extensibility: drop a routing-skills/<name>/{description.txt, SKILL.md} pair into the repo and run bl setup --sync. SHA-256 delta-check picks up the addition; the curator reads it on next session wake.

---

Bash SDK: 136 reusable bl_* primitives

bl is not just a CLI; it is a bash SDK. Source bl from any other bash tool (source bl || true) and you get reusable primitives for Anthropic Managed Agents, Files, Memory Stores, Skills, Messages API, prompt-injection fencing, ledger writes, outbox rate-limiting, and operator notification, in pure bash, with no Python or service runtime.

| Family | Source | Purpose |
|---|---|---|
| bl_api_* (incl. bl_mem_*, bl_poll_*, bl_jq_*) | 20-api.sh | Managed Agents REST surface; backoff+retry; memory-store CRUD; schema check |
| bl_messages_call | 22-models.sh | Messages API caller (Sonnet 4.6 / Haiku 4.5) |
| bl_files_* | 23-files.sh | Anthropic Files API: upload, attach, GC orphans |
| bl_skills_* | 24-skills.sh | Anthropic Skills API: upload, |
| bl_ledger_* | 25-ledger.sh | Dual-write audit ledger (memory store + local JSONL) |
| bl_fence_* | 26-fence.sh | Prompt-injection fence: session-unique tokens, untrusted-content wrap |
| bl_outbox_* | 27-outbox.sh | Rate-limit queue with watermarks + age-gated drain |
| bl_notify | 28-notify.sh | Multi-channel operator notification |
| bl_trigger_* | 29-trigger.sh | Hook adapters (LMD post_scan_hook today) |
| bl_observe_* | 40-42-observe-*.sh, 45-cpanel.sh | 10 e collectors + helpers + router |
| bl_consult_* / bl_run_* / bl_case_* | 50-70-*.sh | Session lifecycle, step execution, case lifecycle |
| bl_defend_* / bl_clean_* | 82-83-*.sh | Defensi apply, remediation with backup + diff + undo |
| bl_setup_* | 84-setup.sh | Workspace bootstrap, idempotent skill upload, CAS update, archive |

Full SDK reference: PRD.md §5.0.1.

---

What blacklight is NOT

Explicit non-goals. Not in this , not in any :

---

Proof

Beha is committed e, not a claim. Four artifacts:

---

Roadmap

Multi-tenant SaaS tracked under T8; the OSS CLI stays GPL v2. Thirty items across eight strategic themes scoped in FUTURE.md.

---

Further reading

| Surface | Path |
|---|---|
| Architecture and command reference | DESIGN.md |
| Executi, problem, users, competiti | PRD.md |
| Roadmap with item-le briefs | FUTURE.md |
| Setup contract · action tiers · security model | docs/setup-flow.md · docs/action-tiers.md · docs/security-model.md |
| State schema · case layout · threat context · exit codes | docs/state-schema.md · docs/case-layout.md · docs/threat-context.md · docs/exit-codes.md |
| Managed Agents API surface | docs/managed-agents.md |
| Li smoke + trace e | tests/live/ |
| Command help | bl --help and bl <verb> --help |

---

License

GNU GPL v2. See LICENSE.

Part of the rfxn defensive OSS portfolio, alongside LMD, APF, and BFD. blacklight is about which detection tools sit on top of the Linux substrate; the rfxn family is one anchor case, not a precondition.

R-fx Networks <> · Ryan MacDonald <>.

---

*Hackathon build · Opus 4.7 + Anthropic Managed Agents · Cerebral "Built with 4.7" April 2026.*

项目信息

开发语言：Shell

Star 数：14

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕The future is Mythos-class agents that take vuln-to-exploits from days to hours, Linux defense is still stuck at human speed. Blacklight is the agentic counter-measure: a skills-native Managed Agent that directs OSS defensive primitives at the speed of the attack. GPL v2. (Opus 4.7 hackathon)展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。