# Fleet Immune System

**Treat normalized scan findings as immune signals: discover patterns, synthesize non-executing defenses, remember what worked.**

Treats normalized scan findings as immune signals: discovers co-occurring fleet threat patterns, synthesizes non-executing defensive recipes, retains successful outcomes as recallable memory, and targets adjacent cohorts likely to show the same variant.

It is an analysis and decision surface, not an actuator: it has no network client, touches no files, spawns no processes, and reads no environment variables.

## Why a practitioner would install this

- **Findings stop being a flat list.** Co-occurrence across the fleet is surfaced as a supported pattern with the signals that support it, so related exposure is treated as one condition.
- **Defensive recipes never execute.** A synthesized antibody is a described, reviewable response plan — the server has no actuator and cannot run it.
- **Successful responses are remembered.** A crystallized outcome is recallable by pattern similarity, so the second occurrence does not restart the analysis.
- **Adjacent cohorts get named.** The cycle planner points at neighbours in the supplied topology that are likely to carry the same variant, before they are scanned.
- **Breeding cannot escalate.** Combining two recipes is deterministic and may not introduce destructive action absent from both parents.

## Behavioural contract

1. `immune_discover` returns co-occurring patterns that meet an explicit minimum support; unsupported coincidence is not a pattern.
2. `immune_synthesize` produces a non-executing antibody recipe from a pattern and its signals.
3. `immune_cycle` plans one cycle: patterns, variants, memory recall and adjacent-cohort targets from the supplied topology.
4. `immune_crystallize` retains a pattern/antibody/outcome above a confidence floor into session-local immune memory.
5. `immune_recall` returns the closest retained crystal for a pattern, or nothing when similarity is below the threshold.
6. `immune_breed` deterministically combines two recipes and refuses to escalate destructive action beyond both parents.
7. Unknown fields, malformed signals and out-of-range thresholds fail closed.

## Prerequisites

- Node.js 20 or newer (`node --version`). Zero runtime dependencies.
- An MCP client that speaks stdio (Claude Code, Claude Desktop, Cursor), or direct library use from TypeScript.
- No API key, account, network access or Tenable product is required.

## Install and run

```bash
git clone https://github.com/SweetKenneth/shpbl-fleet-immune-system.git
cd shpbl-fleet-immune-system
npm install      # devDependencies only: typescript
npm run build    # compiles to dist/
npm test         # 38 behavioural, boundary and fail-closed tests
npm start        # starts the MCP server on stdio
```

MCP client configuration:

```json
{
  "mcpServers": {
    "fleet-immune-system": {
      "command": "node",
      "args": ["/absolute/path/to/shpbl-fleet-immune-system/dist/src/mcp-server.js"]
    }
  }
}
```

## Tools exposed

- `immune_discover` — Discover co-occurring emergent fleet threat patterns from normalized defensive scan signals.
- `immune_synthesize` — Synthesize a non-executing defensive antibody recipe from a threat pattern.
- `immune_cycle` — Plan one fleet immune cycle with variants, memory recall and adjacent cohort targeting.
- `immune_crystallize` — Persist a successful pattern/antibody outcome into the server-local immune memory for later recall.
- `immune_recall` — Recall the closest retained immune-memory crystal for a threat pattern.
- `immune_breed` — Breed two non-executing antibody recipes into a deterministic next-generation candidate without escalating destructive action.

## What it outputs

Supported threat patterns, non-executing antibody recipes, one-cycle plans with variant and adjacent-cohort targeting, memory crystals and recall matches with similarity scores.

## Verification

Reproduce all of it from a clean clone with `npm run check`:

- Strict TypeScript compile and `--noEmit` typecheck: **PASS**
- Behavioural tests: **38/38 PASS**
- Randomised invariant hammer: **30,000 cases / 210,000 invariant checks PASS**
- Static scan for network, filesystem, process and dynamic-eval surfaces in `src/`: **PASS (0 findings)**
- Worked example runs end to end: **PASS**
- Runtime dependencies: **0**

## Known limitations

- No scanner, cloud or network client is embedded; normalized signals are supplied by the caller.
- Pattern support is a co-occurrence measure over the signals you supply, not a causal claim.
- Antibody recipes are descriptions for human or adapter execution. Nothing here applies a change.
- Immune memory is session-local; exported crystals are the durable artifact.

## Provenance and lineage

This product exists because two things were put together, and both are credited.

**Upstream capability inspiration — [`conard0-git/targeted-nessus-scan`](https://github.com/conard0-git/targeted-nessus-scan)**, by Isaac Conard (conard0-git), MIT licensed. Its observed behaviour was studied as a capability surface: what a practitioner in that domain actually needs to do. The exact paths and lines that were read are recorded in [`PROVENANCE.json`](./PROVENANCE.json). **No line of upstream implementation code is used in this package.** The upstream licence text is preserved under `THIRD_PARTY_NOTICES/` as provenance; it does not license this implementation.

**SHPBL capability library — [shpbl.com](https://shpbl.com).** SHPBL ([shpbl.com](https://shpbl.com)) is a governed library of reusable software capabilities and a method for composing them: it reads a target repository, identifies what capability it demonstrates, matches that against owned capability records, and writes new software where neither side had it before. The capability parents used here are listed by identifier in `PROVENANCE.json`. **No harvested capability body is embedded in this package.**

**The implementation in this repository was written fresh** from the approved capability contract for this run. The literal composition is 0% upstream code, 0% copied SHPBL capability bodies, 100% new implementation. That is an exact-line and byte-level statement about this source tree, not a legal opinion.

Author and copyright: **Kenneth E. Sweet Jr.**, MIT licensed.

Attribution does not imply endorsement by Isaac Conard (conard0-git), Tenable, or any other party.

## Tenable status

Submitted to the Tenable CyberAgents Exchange for review on September 14, 2026 — [pull request #172](https://github.com/tenable/cyberagents-exchange/pull/172).
Submission does not imply review, approval, certification, validation, endorsement or acceptance by Tenable.

## Files

- `src/` — implementation and the stdio MCP server.
- `tests/` — behavioural, fail-closed and MCP integration tests.
- `scripts/` — randomised invariant hammer and the static security scan.
- `examples/worked-example.ts` — an end-to-end run you can execute.
- `SECURITY.md` — threat boundary and forbidden behaviour.
- `PROVENANCE.json` — upstream and SHPBL capability lineage.
- `MANIFEST.json` / `CHECKSUMS.sha256` — released file inventory and hashes.
- `LICENSE` — MIT.

## License

MIT © 2026 Kenneth E. Sweet Jr.. See [`LICENSE`](./LICENSE).