Counter-Agent Swarm

Small defensive glue connecting deterministic request screening, an external unmodified Mothership, and external DeadBolt 2.0.0. One protected application per instance. No new dashboard. This repository is Apache-2.0; the dependencies retain their own licenses. Mothership is currently proprietary and must be obtained separately with permission. An open-source glue layer does not make the entire dependency stack open source.

Status: local synthetic integration proof, not production protection. Real Mothership → stdio MCP → native DeadBolt kill/deny/revoke acceptance passes. The analyst in that proof is a deterministic test fixture. Live frontier-model analysis, hostile-payload detonation, production deployment, performance under attack and independent adversarial evaluation remain unvalidated. No protected real application has been changed or deployed by this project.

Created by NextEleven. The public component suite can be evaluated without Mothership or a model credential; full native integration needs separately authorized engine access. See the pilot test guide, glossary, validation evidence and contributors and testers.

Start here: public component preview

Source: https://github.com/seanebones-lang/counter-agent-swarm

Volunteer testers and contributors are welcome. Participation is unpaid, with public contributor/tester credit by agreement. Read CONTRIBUTING.md for scope, results, private security reporting and attribution.

The October 24 packaged CI run passed all 76 public component tests as an ordinary user on Ubuntu with Python 3.12 and 3.13, and macOS with Python 3.13. An external tester separately reported the earlier 69-test suite passing with Python 3.12.3 on Ubuntu 24.04/WSL2 as root; ordinary-user WSL verification remains a separate follow-up. See the pilot guide for Ubuntu venv prerequisites. Use a fresh ordinary-user environment; native Windows is not supported by the Unix worker/permission code. No model key, private engine, cloud account or production application is needed:

git clone https://github.com/seanebones-lang/counter-agent-swarm.git
cd counter-agent-swarm
python3.13 -m venv .venv
.venv/bin/python -m pip install '.[test]'
.venv/bin/python scripts/collect_component_results.py --out ./component-results

The collector runs the explicit public subset, currently 81 tests, and writes results.json, test-output.txt and feedback.md. It uploads nothing. Inspect and redact the files before sharing. Use a new output directory for another run. Do not run the entire pytest directory without the separately authorized native dependencies: it contains Mothership-specific tests. Public component results do not establish actual native integration, live model judgment or deployment.

Source distributions include tests, scripts, examples and instructions. The smaller wheel contains the glue runtime only. Public CI builds and installs the source distribution outside the checkout before running the component suite. For history, the first public run passed the earlier 69-test suite on Ubuntu and macOS with Python 3.13. Component CI does not validate native-engine deployment or sandbox isolation. The separate validation evidence table distinguishes these runs from the operator-hosted native lab and external reports.

Related MCP server: UVG Local MCP Server

Architecture

For an operator-hosted real-engine pilot that keeps Mothership private, see the Linux native lab guide. Its public tester kit contains only a client and instructions; the private runtime image stays with the operator. Live analyst judgment and hostile-payload detonation remain separate scopes.

request → bounded deterministic proxy → fresh DeadBolt admission → fixed private origin
              │ suspicious: 403                │ unavailable/denied: 503
              └→ authenticated metadata ingress → bounded durable transport queue
                                                     │ off path
                                     existing Mothership memory + swarm.analyze
                                                     │ native owner approval
                                            swarm.kill / deny / revoke
                                                     │ fixed-target stdio MCP
                                           external DeadBolt CLI / store

official CISA KEV → reviewed inventory selection → Mothership memory (untrusted)
separate isolated sandbox host → immutable rule proposals → human review

Detection and enforcement contain no AI calls. A suspicious request is denied before incident delivery or analysis. Benign forwarding requires a fresh exact DeadBolt allow; missing credentials, invalid replies, unavailable services and damaged lease stores cannot authorize forwarding. The protected origin must be private: direct origin access bypasses a cooperative proxy.

The model can recommend an action, not approve it. Every new model analysis and system-wide control action requires Mothership's native approval. Analysis runs inside the glue-owned swarm.analyze tool registered into an unmodified Mothership application bootstrap. There is no invented Mothership plugin/configuration API. The existing dispatcher supplies scope checks, idempotency, approvals and evidence.

Optional native proof with separately authorized dependencies

For component testing without the private runtime, install .[test] into a new environment and run python scripts/test_glue_only.py. This deliberately excludes native integration rather than silently substituting an imitation engine.

Prerequisites: Python 3.12 or 3.13 in the recorded tested environments, a separately installed reviewed Mothership 0.3.0, native DeadBolt 2.0.0, and the dependencies in pyproject.toml. Install Mothership from your authorized source/artifact; do not install an unrelated similarly named public package.

python -m venv .venv
.venv/bin/python -m pip install /absolute/path/to/reviewed-mothership.whl
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/python -m pytest -q
.venv/bin/python scripts/acceptance.py --deadbolt /absolute/path/to/deadbolt --out docs/acceptance.json

The harness creates disposable private stores and identities, starts real services on loopback, and checks an independent upstream request counter. It verifies:

• Healthy request: 200 and one upstream request.

• Inert exploit-shaped indicator: 403 and no additional upstream request.

• Incident recorded in native Mothership memory; action waits for approval.

• Owner fixture approves; actual external stdio MCP calls actual DeadBolt.

• Kill, clip-forwarding deny and admission-credential revocation independently block the next benign request with 503; the upstream count remains unchanged.

• Same-key receipt replay creates no second native control event.

• A separate controller still reads evidence after the target is killed.

• Missing credentials, a broken disposable lease table and a stopped gate deny.

• Temporary services and stores are cleaned up.

See the retained acceptance receipt. This is protocol automation by the development team, not an independent or model-operated test. The opt-in native pytest also runs when COUNTER_SWARM_TEST_DEADBOLT is set.

Tools and trust boundaries

The MCP facade accepts a reason and incident ID, never a target, URL, shell command, database path or credential. The trusted owner-only binding selects those. No provisioning, renewal, resume or approval tools are exposed through this facade. MCP uses local stdio, not an unauthenticated network listener.

Use separate DeadBolt runs for the controller and protected target. The controller's native allowlist should contain only swarm.kill,swarm.deny,swarm.revoke,swarm.evidence, swarm.analyze,memory.put,memory.get,memory.checkpoint_save as required. Mark those as offline tools when using destination policies, because these dedicated adapters own their fixed endpoints. Do not grant generic http.request to the controller. Owner routes and approvals.wait remain subject to native Mothership semantics.

DeadBolt kill is next-admission enforcement, not termination of in-flight HTTP requests, OS processes or malicious code already executing in an application. A same-user/root process able to edit credentials, policies, binaries or stores is outside this cooperative enforcement boundary. Events are local records, not independent evidence custody.

Per-system runtime

Copy the example JSON files into a private directory outside Git. Set their real fixed identifiers and origins, permissions 0600 for files and 0700 for directories. Provision both native runs/policies/credentials first using reviewed DeadBolt tools. Create the Mothership controller through its existing owner API, using examples/mothership-agent.json. The native acceptance script is an executable provisioning reference for disposable identities.

Set the paths and mandatory native gate configuration shown in .env.example. The processes can be started individually:

python -m uvicorn counter_swarm.mothership_ext:create_app --factory --host 127.0.0.1 --port 9783 --no-access-log
python -m uvicorn counter_swarm.runtime:configured_ingress --factory --host 127.0.0.1 --port 9784 --no-access-log
python -m uvicorn counter_swarm.runtime:configured_proxy --factory --host 127.0.0.1 --port 8080 --no-access-log
counter-swarm work
counter-swarm status
counter-swarm resume --event-id ORIGINAL_INCIDENT_ID

Start DeadBolt's authenticated loopback sidecar separately against the same trusted database/events binding. work handles one queued incident. Default behavior saves the finding and escalates in Mothership, with no model request or system-wide action. An authenticated metadata ingress queues at most 2,048 content-addressed incidents; duplicate IDs do not enqueue twice. Queue-full/delivery failures leave suspicious requests blocked and emit a bounded delivery-failure log. Archive completed incidents under an operator-approved retention policy; this prototype does not silently evict pending or uncertain work.

Use the explicit operator command counter-swarm archive-completed --destination /absolute/private/archives/new.jsonl to durably export completed records and reclaim their slots. See queue operations for failure reconciliation and the public listener's resource bounds.

Claims become held before remote work. A crash or unknown outcome requires operator reconciliation. resume only waits on the saved original approval; it cannot approve it, silently requeue a held incident or generate a new action key. Mothership's stored results are the authoritative execution receipts.

Optional frontier analysis

Live calls default to zero even when a key exists. To enable an approved trial, configure COUNTER_SWARM_MODEL with an available reviewed model, COUNTER_SWARM_MODEL_BUDGET_FILE with a persistent private absolute SQLite path, COUNTER_SWARM_MAX_MODEL_CALLS with an explicitly approved allowance (1–100), and set live_analysis: true in the runtime JSON. Load OPENAI_API_KEY through a private runtime secret mechanism. No secret is included in examples, images or receipts.

The initial provider adapter uses OpenAI's Responses API with strict structured output, store: false, 600 output tokens maximum, a total request deadline, and at most 4 KiB of projected input. It sends only opaque fingerprint/incident IDs, known detector rule IDs and severity/revision. It sends no raw body, URL, request header or client address, and gives the model no tools. Other providers implement the small Analyst protocol; detector, gate and approval logic do not change.

Persistent call reservations are consumed before network activity, including failed requests. There are no automatic retries/resets. This is a call-count cap, not an account-wide currency cap; model pricing and provider billing limits are separate. Exact-system/evidence cache entries expire after 60 seconds and never authorize admissions or reuse authority for merely similar payloads.

Sandbox, intel and deployment

See worker commands, sandbox boundary, Railway staging profile, and security limits. The sandbox adapter does not supply or validate a production detonation image. Ordinary shared Railway containers are not the isolation boundary for exploit execution. Generated signatures remain review proposals; no automated active-rule promotion or honeypot deployment is included.

Why this is bounded

Current indicators cover a small, explicit corpus: two layers of URL encoding, case/Unicode normalization, selected PHP execution/CGI indicators, suspicious RSC prototype strings, ambiguous framing, unsupported compressed request bodies and resource limits. They can miss attacks and flag legitimate requests. Blocking all compressed request bodies is a conservative compatibility tradeoff, not Brotli exploit identification. This proxy intentionally limits requests to 64 KiB and buffers upstream responses up to 2 MiB; WebSockets, streaming/SSE, large uploads and general-purpose transparent proxying are unsupported.

Patching vulnerable runtimes remains essential. This project is not a cure for all PHP/Node/Next.js vulnerabilities or a substitute for application security and tested incident response. Evaluate false positives, parser differentials, real deployment bypasses, recovery and sustained load on staging before protecting a real system. The first useful milestone is reproducible scoped containment, not an AI allowed to rewrite production security policy from attacker-supplied text.