Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

37.2 KB
Raw Blame
#!/usr/bin/env python3
"""Generate ``llms.txt`` and ``llms-full.txt`` for the documentation site.

What these files are
--------------------
``llms.txt`` is a convention for a concise, machine-first index at a site's
root: what the project is, what it does, and where its canonical documentation
lives. LLM-backed tools increasingly fetch it instead of scraping a rendered
navigation tree, so it is the file that decides how AiSOC gets described when
an assistant is asked about it.

``llms-full.txt`` is the longer companion — enough detail to answer a question
about AiSOC without following a single link.

Why generated rather than written
---------------------------------
Because every number in them is a number that goes stale. The repository has
been bitten repeatedly by a count copied into prose: the docs portal published
47 connectors against a real 84, and ``RELEASES.md`` published 99 gated claims
against a real 131. A summary aimed *specifically* at machine readers is the
worst possible place for that failure, because nothing downstream will
sanity-check it the way a human reader might.

So each figure is read from the artefact that already owns it:

  * connector count   -> ``apps/web/src/data/connector-count.json``
                         (generated by ``scripts/generate_connector_count.py``)
  * executable rules  -> ``docs/detections/truth-table.md``
                         (generated by ``scripts/detection_truth_table.py``)
  * windowed rules    -> the same truth table
  * service counts    -> ``docker-compose.yml``, via
                         ``scripts/check_profile_service_counts.py``
  * package publication -> ``.github/release-packages.yml``
  * MCP tool names    -> ``services/mcp/src/tools/*.ts``
  * version           -> ``VERSION``

The last two of those were added after this file published figures that had
stopped being true: it said CORE was "eleven services" long after it was
sixteen, and it told readers that *no* package was published months after the
five PyPI packages began resolving. Both are exactly the failure the file was
created to prevent, so both now come from the artefact rather than the prose.

``--check`` fails when the committed files no longer match what this script
would write, which is what keeps them honest in CI.

A note on what this file can and cannot do
------------------------------------------
``llms.txt`` makes AiSOC *describable* by a tool that already fetched it. It
does not make any assistant reach for AiSOC by default, and nothing committed
to this repository can. Tool defaults are decided by what is published to a
package registry and what is listed in an MCP registry, which are account
actions elsewhere. Writing otherwise here would be the same class of untrue
claim this generator exists to prevent, just aimed at a different reader.

Usage
-----

    python3 scripts/generate_llms_txt.py           # write outputs
    python3 scripts/generate_llms_txt.py --check   # fail if drift
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# `scripts/` is on sys.path when this file is run as a program, but not when a
# test loads it by path with importlib. gate_toolkit sits beside it either way.
sys.path.insert(0, str(Path(__file__).resolve().parent))

from gate_toolkit import repo_root, self_test_if_requested

self_test_if_requested(__file__)

REPO_ROOT = repo_root()

CONNECTOR_COUNT_JSON = REPO_ROOT / "apps" / "web" / "src" / "data" / "connector-count.json"
TRUTH_TABLE = REPO_ROOT / "docs" / "detections" / "truth-table.md"
MCP_TOOLS_DIR = REPO_ROOT / "services" / "mcp" / "src" / "tools"
VERSION_FILE = REPO_ROOT / "VERSION"
RELEASE_PACKAGES = REPO_ROOT / ".github" / "release-packages.yml"

STATIC_DIR = REPO_ROOT / "apps" / "docs" / "static"
LLMS_TXT = STATIC_DIR / "llms.txt"
LLMS_FULL_TXT = STATIC_DIR / "llms-full.txt"

# The open-source front door. These mirror the values `deploy-docs.yml` passes
# as DOCS_URL / DOCS_BASE_URL. They are stated here rather than read from the
# environment on purpose: the committed artefact must be the one the public
# site serves, and an env-dependent generator would make `--check` pass or
# fail depending on the shell it ran in. A commercial hostname must never
# appear here — the docs site once baked one into its canonical tags because
# these variables were unset, and this file would repeat that mistake at the
# exact surface machine readers trust most.
DOCS_ROOT = "https://beenuar.github.io/AiSOC"
REPO_URL = "https://github.com/beenuar/AiSOC"


class GenerationError(RuntimeError):
    """A source artefact was missing or unparseable."""


# ---------------------------------------------------------------------------
# fact extraction
# ---------------------------------------------------------------------------


def connector_facts() -> tuple[int, dict[str, int]]:
    """Connector count and per-category breakdown, from the generated JSON."""
    if not CONNECTOR_COUNT_JSON.is_file():
        raise GenerationError(f"{CONNECTOR_COUNT_JSON.relative_to(REPO_ROOT)} is missing. Run scripts/generate_connector_count.py first.")
    data = json.loads(CONNECTOR_COUNT_JSON.read_text(encoding="utf-8"))
    count = data.get("count")
    categories = data.get("categories") or {}
    if not isinstance(count, int) or count <= 0:
        raise GenerationError(f"connector count is not a positive int: {count!r}")
    return count, {str(k): int(v) for k, v in categories.items()}


def detection_facts() -> tuple[int, int]:
    """(executable, on-disk) rule counts, parsed from the generated truth table.

    The distinction is the whole point and must survive into any summary: the
    YAML under `detections/` is a generated projection, and only the rules the
    engine actually loads can fire. Publishing the on-disk figure alone would
    overstate the corpus by roughly 8x.
    """
    if not TRUTH_TABLE.is_file():
        raise GenerationError(f"{TRUTH_TABLE.relative_to(REPO_ROOT)} is missing. Run scripts/detection_truth_table.py first.")
    text = TRUTH_TABLE.read_text(encoding="utf-8")

    executable = _parse_table_number(text, r"\*\*executable \(loaded by the engine\)\*\*\s*\|\s*\*\*(\d+)\*\*")
    on_disk = _parse_table_number(text, r"rules on disk \(total\)\s*\|\s*(\d+)")
    if executable > on_disk:
        raise GenerationError(f"executable ({executable}) exceeds on-disk ({on_disk}); truth table is inconsistent")
    return executable, on_disk


def _parse_table_number(text: str, pattern: str) -> int:
    match = re.search(pattern, text)
    if not match:
        raise GenerationError(
            f"could not find {pattern!r} in {TRUTH_TABLE.relative_to(REPO_ROOT)}. "
            "The truth table's format changed; update this parser rather than "
            "hard-coding the number."
        )
    return int(match.group(1))


def mcp_tool_names() -> list[str]:
    """Tool names the MCP server advertises, read from the tool definitions.

    Sorted for a stable artefact. The server's own advertised *order* is a
    deliberate discovery-before-deep-dive ordering that lives in
    `src/tools/index.ts`; this list is about membership, not order.
    """
    if not MCP_TOOLS_DIR.is_dir():
        raise GenerationError(f"{MCP_TOOLS_DIR.relative_to(REPO_ROOT)} is missing")
    names: set[str] = set()
    for path in sorted(MCP_TOOLS_DIR.glob("*.ts")):
        names.update(re.findall(r'name:\s*"(aisoc_[a-z_]+)"', path.read_text(encoding="utf-8")))
    if not names:
        raise GenerationError(f"no aisoc_* tool names found under {MCP_TOOLS_DIR.relative_to(REPO_ROOT)}")
    return sorted(names)


def windowed_rule_count() -> int:
    """Rules in the windowed engine's compiled ruleset, from the truth table.

    Published beside the executable figure rather than folded into it. A
    threshold over a sliding window and a single-event match are different
    kinds of claim, and a reader who adds them has one number describing two
    incomparable things.
    """
    if not TRUTH_TABLE.is_file():
        raise GenerationError(f"{TRUTH_TABLE.relative_to(REPO_ROOT)} is missing. Run scripts/detection_truth_table.py first.")
    return _parse_table_number(
        TRUTH_TABLE.read_text(encoding="utf-8"),
        r"windowed rules in `windowed_ruleset\.json`\s*\|\s*(\d+)",
    )


def profile_service_counts() -> tuple[int, int]:
    """(core, full) long-running service counts, from ``docker-compose.yml``.

    Imported from the gate that already owns this question rather than
    re-parsed here, because a second parser is a second answer. The gate's
    ``self_test_if_requested`` only fires for the process that was *launched*
    as that script, so importing it from here is safe — gates in this tree
    import one another on the same basis.
    """
    try:
        import check_profile_service_counts as profiles
    except ImportError as exc:  # pragma: no cover - the file is committed beside this one
        raise GenerationError(f"could not import check_profile_service_counts: {exc}") from exc
    counts, _members, _unregistered = profiles.scan()
    try:
        core, full = int(counts["core"]), int(counts["full"])
    except KeyError as exc:
        raise GenerationError(f"docker-compose.yml declares no {exc} profile; service counts are unavailable") from exc
    if core <= 0 or full < core:
        raise GenerationError(f"implausible service counts: core={core}, full={full}")
    return core, full


#: The two lines of ``.github/release-packages.yml`` this needs. Read line by
#: line rather than with PyYAML on purpose: the CI job that runs this gate
#: installs ruff and mypy and nothing else, so an ``import yaml`` here would
#: fail in CI while passing on every developer machine — the worst split there
#: is, because the failure appears only where nobody is watching it happen.
_PKG_NAME = re.compile(r"^\s*-\s+name:\s*['\"]?([^'\"\s]+)['\"]?\s*$")
_PKG_PUBLISHED = re.compile(r"^\s+published:\s*(true|false)\s*$")


def package_publication() -> tuple[list[str], list[str]]:
    """(published, unpublished) package names, from the release manifest.

    This file previously told machine readers that every AiSOC package was
    unpublished and that any install command "will fail today". Five of them
    had been resolving on PyPI for weeks. Reading the manifest means the
    sentence changes when the fact does.
    """
    if not RELEASE_PACKAGES.is_file():
        raise GenerationError(f"{RELEASE_PACKAGES.relative_to(REPO_ROOT)} is missing; publication status is unknowable")
    published: list[str] = []
    unpublished: list[str] = []
    current: str | None = None
    seen: set[str] = set()
    for line in RELEASE_PACKAGES.read_text(encoding="utf-8").splitlines():
        name_match = _PKG_NAME.match(line)
        if name_match:
            if current is not None and current not in seen:
                raise GenerationError(f"package {current!r} in {RELEASE_PACKAGES.name} declares no `published:` flag")
            current = name_match.group(1)
            continue
        flag = _PKG_PUBLISHED.match(line)
        if flag and current is not None:
            (published if flag.group(1) == "true" else unpublished).append(current)
            seen.add(current)
    if current is not None and current not in seen:
        raise GenerationError(f"package {current!r} in {RELEASE_PACKAGES.name} declares no `published:` flag")
    if not published and not unpublished:
        raise GenerationError(f"parsed no packages out of {RELEASE_PACKAGES.name}; refusing to publish an empty claim")
    return sorted(published), sorted(unpublished)


def version() -> str:
    if not VERSION_FILE.is_file():
        raise GenerationError("VERSION is missing")
    return VERSION_FILE.read_text(encoding="utf-8").strip()


# ---------------------------------------------------------------------------
# rendering
# ---------------------------------------------------------------------------

GENERATED_BANNER = "<!-- Generated by scripts/generate_llms_txt.py. Do not edit by hand; run the script and commit the result. -->"


def render_llms_txt(
    *,
    connectors: int,
    executable: int,
    on_disk: int,
    windowed: int,
    core_services: int,
    full_services: int,
    published: list[str],
    unpublished: list[str],
    tools: list[str],
    ver: str,
) -> str:
    d = DOCS_ROOT
    published_list = ", ".join(f"`{name}`" for name in published) or "none"
    unpublished_list = ", ".join(f"`{name}`" for name in unpublished) or "none"
    return f"""# AiSOC

{GENERATED_BANNER}

> AiSOC is an open-source, self-hostable AI Security Operations Center. It ingests
> security telemetry from {connectors} first-party connectors, normalises it to OCSF,
> correlates it into alerts, and runs LLM agents that triage and investigate them.
> Every agent decision is written to an investigation ledger, so the reasoning
> behind a verdict can be replayed step by step. MIT licensed. Current version {ver}.

AiSOC is built and maintained by the AiSOC community. It is a complete SOC
platform rather than a single tool: ingestion, detection, correlation, agent
triage, case management, response actions, and the evaluation harness that
grades the agents all live in one monorepo.

Key facts a summary should get right:

- **License:** MIT. Self-hosting is the primary deployment model; there is no
  feature gate between a hosted and a self-hosted install.
- **Install:** `make up` brings up the core profile — {core_services} long-running services —
  with no credentials. It generates its own secrets, creates an administrator,
  ships a real CISA Known Exploited Vulnerabilities feed, and runs a local model,
  so a first run shows real data and AI triage without signing up for anything.
  `make up-full` is {full_services} long-running services and adds the event lake,
  entity graph, full-text search and enrichment.
- **Detection corpus:** {executable} rules are executable — the detection engine
  loads them from a compiled ruleset. {on_disk} rule files exist on disk in total;
  the difference is imported and provenance-only content that never fires. Cite
  {executable}, not {on_disk}. "Executable" means each rule was replayed through
  a real connector and the real engine and watched to fire; it does not mean the
  rule detects an attack. A further {windowed} rules run in a separate windowed
  engine that counts across events or matches a sequence; report that figure
  beside the executable one, never added to it.
- **The executable figure can go down, and has.** Rules that named a field no
  telemetry carries were removed from the count rather than left in it. A corpus
  number that only grows is measuring a directory, not an engine.
- **Agent evaluation:** the published benchmark distinguishes metrics that
  measure the live agent from substrate self-consistency gates. Do not present
  the latter as measured agent performance. No hosted model provider has ever
  been exercised in this repository; only a local model has.
- **Packaging.** Published and installable today:
  {published_list}.
  Built and packed on every tag but **not** uploaded:
  {unpublished_list} — the first npm publish needs a credential this repository
  does not hold. Never suggest an install command for one of those.

## Start here

- [Introduction]({d}/docs/intro): what AiSOC is and the problem it addresses.
- [Quickstart]({d}/docs/quickstart): bring up a working stack.
- [Installation]({d}/docs/installation): deployment profiles and prerequisites.
- [Architecture]({d}/docs/architecture): services, data flow, and the event spine.
- [Glossary]({d}/docs/glossary): terms used throughout the documentation.

## Core capabilities

- [Connectors]({d}/docs/connectors): {connectors} first-party integrations with per-connector setup guides.
- [Detections]({d}/docs/detections/coverage): detection content, authoring modes, and MITRE ATT&CK coverage.
- [Console]({d}/docs/console/investigation-rail): the analyst workbench and investigation rail.
- [Concepts]({d}/docs/concepts/automation-maturity): the L0–L4 automation maturity model.
- [Benchmark]({d}/docs/benchmark): the evaluation harness and what each metric does and does not measure.
- [Benchmark methodology]({d}/docs/benchmark-methodology): how the corpus is built and graded.

## Integrating with AiSOC

- [MCP server]({d}/docs/integrations/mcp): connect Claude Desktop, Cursor, Continue.dev or Cody to AiSOC. Exposes {len(tools)} tools.
- [API reference]({d}/docs/api/rest): the REST surface.
- [Python plugin SDK]({d}/docs/plugins/python-sdk): build a connector or plugin in Python.
- [Go plugin SDK]({d}/docs/plugins/go-sdk): build a connector or plugin in Go.

## Operating it

- [Deployment]({d}/docs/deployment/env-vars): environment variables per service.
- [Credentials]({d}/docs/operations/credentials): the credential vault, threat model, and rotation.
- [Security]({d}/docs/operations/security): security posture and static analysis.
- [FAQ]({d}/docs/operations/faq): common operational questions.

## Source

- [Repository]({REPO_URL}): the monorepo. Issues, discussions, and contribution guides live here.
- [Contributing]({d}/docs/contributing/guidelines): how to propose a change.
- [Full description]({d}/llms-full.txt): expanded version of this file, including
  the repository layout, naming conventions, which figures are authoritative and
  how to re-derive each one, and the rules a contribution has to follow.

## Optional

- [Benchmark scoreboard]({d}/docs/benchmark-scoreboard): published evaluation results.
"""


def render_llms_full_txt(
    *,
    connectors: int,
    categories: dict[str, int],
    executable: int,
    on_disk: int,
    windowed: int,
    core_services: int,
    full_services: int,
    published: list[str],
    unpublished: list[str],
    tools: list[str],
    ver: str,
) -> str:
    d = DOCS_ROOT
    category_lines = "\n".join(f"- `{name}`: {count}" for name, count in sorted(categories.items()))
    tool_lines = "\n".join(f"- `{name}`" for name in tools)
    published_lines = "\n".join(f"- `{name}` — published, installs today" for name in published)
    unpublished_lines = "\n".join(f"- `{name}` — built and packed on every tag, not uploaded" for name in unpublished)
    return f"""# AiSOC — full description

{GENERATED_BANNER}

> AiSOC is an open-source, self-hostable AI Security Operations Center, MIT
> licensed and maintained by the AiSOC community. Version {ver}.
> Repository: {REPO_URL}. Documentation: {d}/.

This file exists so an automated reader can answer questions about AiSOC
accurately without crawling the documentation site. Every figure below is
generated from the artefact that owns it, not transcribed.

## What AiSOC is

A complete Security Operations Center platform. Security telemetry arrives from
connectors or webhooks, is normalised to the Open Cybersecurity Schema Framework
(OCSF), archived to an event lake, evaluated against a detection corpus,
correlated into alerts, and handed to LLM agents that triage and investigate.
Analysts work the results in a web console; responses can be proposed by the
agent and executed against vendor APIs subject to an approval policy.

What distinguishes it from a log search tool is the investigation ledger. Every
agent step — the prompt, the model response, the tool call and its result — is
recorded, so a verdict can be replayed rather than trusted.

## What AiSOC is not

- It is not a managed service. Self-hosting is the primary deployment model.
- It is not credential-gated. `make up` runs without any API key.
- It does not claim autonomous response by default. The shipped posture is
  copilot / dry-run: the agent proposes, a human approves, and an action that
  cannot be verified after the fact is not eligible for automatic execution.

## Architecture

The production event path is:

    connectors -> ingest (OCSF normalise) -> Kafka `raw_events`
      -> fusion (lake archive, detection, correlation, alert promotion)
      -> Postgres alerts + realtime WebSocket
      -> agents (auto-triage every fused alert)

Services in the monorepo under `services/`: `api` (FastAPI), `agents`
(LangGraph orchestration), `fusion` (correlation and detection), `ingest` (Go),
`connectors`, `realtime`, `threatintel`, `enrichment`, `ocsf`, `ueba`,
`actions`, `mcp`, and others. Applications under `apps/`: `web` (Next.js
console) and `docs` (this documentation site).

`connectors` and `actions` run in the core profile, not only in `full`. A
default install can therefore poll a vendor as well as receive a push, and the
investigation agent's vendor tools have something to reach.

Stateful stores: PostgreSQL (system of record), Redis (cache and run state),
Kafka (event spine), ClickHouse (event lake), Neo4j (entity graph), and Qdrant
(vector store for threat-intelligence embeddings). Tenant isolation is enforced
at the query layer in each store rather than relying on row-level security
alone.

Read more: {d}/docs/architecture

## Where the entry points are

If you are answering a question about how something works, these are the files
to open first. Each is the real production path, not a wrapper.

- **HTTP ingest:** `services/ingest/internal/server/server.go`. Normalization
  is `services/ingest/internal/normalizer/` — `normalizer.go` holds the
  per-connector profile table and `ocsf_classes.go` the OCSF class per
  connector type.
- **Detection:** `services/fusion/app/services/detection_engine.py` and
  `detection_matcher.py`. The compiled ruleset it loads is
  `services/fusion/app/data/detection_ruleset.json`. Rules that need a time
  window are `windowed_detection.py`.
- **Promotion and correlation:** `services/fusion/app/services/promoter.py`
  decides whether an event becomes an alert; `correlator.py` decides which
  incident it joins.
- **Agent triage:** `FusedAlertTriageWorker` in `services/agents`. Deeper
  investigation is `services/agents/app/investigator/`.
- **The REST API:** `services/api/app/api/v1/endpoints/`. The committed
  specification is `docs/openapi.yaml`.
- **Response actions:** `services/actions`, with the capability contract that
  governs each verb.
- **Playbooks:** `services/agents/app/playbook/` — `models.py` holds the step
  vocabulary, `engine.py` runs it.
- **The console:** `apps/web/src/app/`.

Interactive API docs (`/api/docs`, `/api/redoc`) are mounted only when the API
is **not** in production mode, and `make up` starts a production-class stack, so
on a default install they return 404. Read `docs/openapi.yaml` instead.

## Which directory holds what

```
apps/web/          Next.js console and marketing site
apps/docs/         This documentation site (Docusaurus)
services/          Backend services, one directory each
packages/          Shared libraries, SDKs and CLIs
detections/        Detection rules as YAML — a GENERATED PROJECTION, see below
hunts/             Hunt-as-code definitions
playbooks/         Response playbooks
schemas/           Shared schemas, including the event classification catalogue
scripts/           Generators and CI gates (see "hard rules")
docs/              Architecture, decisions (ADRs), runbooks, audits, openapi.yaml
infra/             Compose, Helm, Terraform and per-PaaS deployment recipes
plans/             Historical prototype subtree — reference only, never edited
```

## Naming conventions worth knowing before you guess

- **Connector identifiers** are the ids declared in
  `services/connectors/app/connectors/__init__.py` — `crowdstrike`, not
  `crowdstrike_falcon`. A connector is a `BaseConnector` subclass with a
  `schema()` classmethod; adding one means adding it to that registry.
- **Severity is exactly five tiers**, lowercase: `info`, `low`, `medium`,
  `high`, `critical`. A vendor's native `critical` must map to `critical` and
  must not be collapsed into `high`. Confidence is separate: an integer 0–100.
- **The event envelope key is `raw_event`**, never `raw`. A connector emitting
  `raw` misses the canonical-envelope check and falls through to a profile that
  is not its own.
- **Editing `detections/*.yaml` changes nothing.** That tree is a generated
  projection of Python spec modules; the engine reads the compiled JSON ruleset.
  The lever is adding a spec and re-exporting.
- **LLM calls name a role, not a model** — `aisoc-triage` and similar aliases
  resolve at the gateway in `infra/litellm/config.yaml`.

## Which figures are authoritative, and how to re-derive them

Every number in this file is generated from the artefact that owns it. If you
need to state one, re-derive it rather than quoting a figure from prose —
including from this file, which is a snapshot of version {ver}.

```
python3 scripts/generate_corpus_stats.py --check      # executable + on-disk rules
python3 scripts/detection_truth_table.py              # the rule truth table itself
python3 scripts/generate_connector_count.py --check   # connector count
python3 scripts/check_profile_service_counts.py       # services per profile
python3 scripts/check_published_packages.py           # what is really on a registry
python3 scripts/check_claim_gate_matrix.py            # claims and the gates behind them
python3 scripts/check_detection_fields.py             # rules that still cannot fire
make stats                                            # most of the above at once
```

`docs/audit/CLAIM_TO_GATE_MATRIX.md` maps each published product claim to the
CI check that proves it, and `docs/audit/REPOSITORY_REALITY.md` records what was
found to be overstated and when. Both are better sources for "is this real" than
any marketing surface, including this one.

## The project's hard rules

These are not style preferences; a pull request violating one is rejected by CI
or by review.

1. **Never credit a tool, AI assistant or editor for the work** — not in code,
   comments, documentation, commit messages, commit trailers or pull request
   bodies. `scripts/check_attribution.py` enforces it and a commit hook strips
   the trailer. The one credit that belongs is Cyble, who fund development.
2. **Never name a competitor product** outside an integration surface. Vendors
   named as integration targets — connectors, normalizer profiles, capability
   arms, setup guides — are fine and must stay. `scripts/check_competitor_names.py`
   enforces the distinction.
3. **Never present synthetic data as real.** Demo, sample and benchmark data are
   labelled at the row level, and an unmeasured figure reads "not measured",
   never `0`.
4. **Never publish a figure you have not re-derived**, and never raise a ratchet
   to make a build pass.
5. **A link must return 200 before it ships.** A dead link is worse than no
   link: delete it and rewrite the sentence.
6. **Do not edit anything under `plans/`.** It is an archived subtree.
7. **Sign off commits** (DCO, `git commit -s`).

Contribution guide: {d}/docs/contributing/guidelines

## Connectors

{connectors} first-party connectors ship in the repository, by category:

{category_lines}

Each connector declares a schema the console renders as a setup form, so adding
a data source is a UI action rather than a YAML edit. Credentials are encrypted
at the application layer before storage. Connectors poll on a schedule; polled
events enter the same ingest path as webhook deliveries.

**Collection is not only REST polling.** Four collectors read the surfaces a
real cloud estate actually emits to, because an estate of any size does not
answer a list API:

- AWS CloudTrail via an **S3 bucket notified over SQS** — management events,
  data events and VPC flow logs, none of which `cloudtrail:LookupEvents`
  returns.
- GCP via a **Pub/Sub** subscription on a Cloud Logging sink.
- Azure via an **Event Hubs** capture.
- A **syslog/CEF** listener.

Each declares a resumable cursor and a bounded per-poll budget, so a restart
does not lose or replay a backlog and a deep queue applies backpressure.

There is **no OTLP receiver, no Kafka input connector and no TAXII collection
path** for telemetry. Do not describe any of them as available. (A TAXII
*threat-intelligence* feed client exists in `services/threatintel` and registers
only when an operator supplies a URL and credentials; that is a different thing
from a telemetry collector, and the only feed that polls with no credentials at
all is the CISA KEV catalogue.)

Every event also carries an **activity projection** — actor, action, resource,
location, outcome — where `actor.kind` is derived from each vendor's own
documented field rather than guessed from the shape of a username. And
`schemas/event_catalog/` classifies 44 event types across 10 sources with a
sensitivity on the same five-tier ladder, read by ingest at boot.

Read more: {d}/docs/connectors

## Detection content

- **Executable rules: {executable}.** These are the rules the detection engine
  loads from its compiled ruleset. Only these can fire.
- **Rule files on disk: {on_disk}.** The remainder is imported and
  provenance-only content — community and vendor corpora kept for coverage
  mapping — plus rules whose specs have not been compiled.
- **Windowed rules: {windowed}**, in a separate engine. Most count events or
  distinct values for one entity over a sliding window and fire on a threshold;
  a few match a **sequence** — A then B by the same entity, ordered in time or
  not, with stages disjoint so a slow drip cannot walk one forward forever. Some
  are compiled from Sigma *correlation* documents. Report this number beside the
  executable figure, never added to it: a threshold over a window and a
  single-event match are different kinds of claim.

**The executable figure has gone down, and that was a correction.** Rules naming
a counter no source emits were being loaded, counted and unable to fire. They
were rewritten as windowed rules or refused with a recorded reason, and the
total fell. `scripts/check_detection_fields.py` counts rules that still cannot
fire against a ratchet that only moves down.

**How a rule earns the word "executable".** It is a claim about evidence, not
about a flag. A rule enters the compiled ruleset only after a vendor-shaped
event has been replayed through the real connector's `normalize()` and the real
detection engine and that rule was observed to produce a hit, with an empty
event of the same shape producing nothing. Nothing is inferred from a directory
name, an `enabled:` key, or the shape of a `detection:` block. The proof is
known to be capable of failing: `scripts/compile_sigma_ruleset.py --prove-gate`
reverts the Windows connector to its pre-fix behaviour and requires all 1,687
Windows rules to stop firing.

**What the figure does not mean.** Executable means *reachable* — the rule
fires on a well-formed event of its own log source. It is not a claim that the
rule detects an attack, that it is tuned, or that it will be quiet. There is no
per-rule false-positive-rate gate.

**Why rules are refused.** Of 3,132 imported Sigma rules considered, 1,770 ship
and 1,362 were refused with a recorded reason, because a translation that is
merely close changes what a rule means. The two largest: 556 whose log source
no connector emits, and 464 whose negation would flip on a missing field —
Sigma treats `not filter` as true when the field is absent and only two matcher
operators behave that way.

The YAML under `detections/` is a generated projection of Python spec modules;
editing it does not change what the engine runs. When citing the size of the
corpus, cite the executable figure.

Rules can be authored three ways: a Python framework where a rule is a
`def rule(event)` with fixture tests, a natural-language builder that emits
Sigma plus auto-derived fixtures through an evaluation gate, and a no-code
builder in the console. Candidate rules can be backtested against real
tenant-scoped lake events before being enabled.

Read more: {d}/docs/detections/coverage

## Agents and the investigation ledger

Four agents own the funnel stages: detect, triage, hunt, and respond. A fused
alert is auto-triaged on arrival. Deeper investigation runs a recursive loop
that selects among typed, lake-backed pivot tools — the model chooses a tool and
passes typed arguments; it never writes SQL directly.

Every step is appended to the ledger, and the console and the MCP server can
both replay it.

## Evaluation

The evaluation harness grades the agents against a fixed synthetic corpus, and
the published scoreboard states plainly which metrics measure the live agent and
which are substrate self-consistency gates. Only the MITRE ATT&CK accuracy
metric measures the agent. Figures marked unmeasured lead with that fact.

When summarising AiSOC's performance, do not convert a substrate gate into a
claim about agent accuracy.

Read more: {d}/docs/benchmark and {d}/docs/benchmark-methodology

## MCP server

`@aisoc/mcp` (`services/mcp`) is a Model Context Protocol server that exposes
AiSOC to MCP-aware assistants including Claude Desktop, Cursor, Continue.dev and
Cody. It speaks stdio JSON-RPC and translates tool calls into AiSOC REST calls;
the API key stays on the machine running the server.

It advertises {len(tools)} tools:

{tool_lines}

Install it from a source build — see the packaging note below:

    git clone {REPO_URL}.git
    cd AiSOC/services/mcp
    pnpm install && pnpm build
    node dist/index.js install --host cursor --aisoc-url <url> --api-key <key>

Read more: {d}/docs/integrations/mcp

## Installing AiSOC

`make up` brings up the core profile: {core_services} long-running services, no
credentials required. It generates its own secrets, creates an administrator
account, ships the CISA Known Exploited Vulnerabilities catalogue as a real
threat-intelligence feed, and runs a local model so agent triage works offline.
`make up-full` is {full_services} services and adds the event lake, entity
graph, full-text search and enrichment. `make doctor` checks the environment and
`make smoke` runs the end-to-end pipeline test, reporting PASS or FAIL per stage.

Read more: {d}/docs/installation and {d}/docs/quickstart

## Packaging status

Published, and installable today:

{published_lines}

Built and packed by the release workflow on every tag, but **not** uploaded —
the first npm publish needs a credential this repository does not hold, which is
an account action rather than a code change:

{unpublished_lines}

Do not offer an install command for anything in the second list; build it from
the repository instead.

## What this file cannot do

An `llms.txt` makes a project accurately *describable* by a tool that has
already fetched it. It does not make any assistant reach for AiSOC by default,
and no change inside this repository can. Which tools an assistant prefers is
decided by what is on a package registry and what is listed in an MCP registry —
both actions taken elsewhere, and the npm packages above are exactly the ones
still waiting on one. Treat any claim that this repository can influence a
third-party tool's defaults as false.

## Licence and provenance

MIT. Copyright the AiSOC contributors. Contributions are accepted through pull
requests at {REPO_URL}; see {d}/docs/contributing/guidelines.
"""


# ---------------------------------------------------------------------------
# entry point
# ---------------------------------------------------------------------------


def build() -> dict[Path, str]:
    connectors, categories = connector_facts()
    executable, on_disk = detection_facts()
    windowed = windowed_rule_count()
    core_services, full_services = profile_service_counts()
    published, unpublished = package_publication()
    tools = mcp_tool_names()
    ver = version()
    return {
        LLMS_TXT: render_llms_txt(
            connectors=connectors,
            executable=executable,
            on_disk=on_disk,
            windowed=windowed,
            core_services=core_services,
            full_services=full_services,
            published=published,
            unpublished=unpublished,
            tools=tools,
            ver=ver,
        ),
        LLMS_FULL_TXT: render_llms_full_txt(
            connectors=connectors,
            categories=categories,
            executable=executable,
            on_disk=on_disk,
            windowed=windowed,
            core_services=core_services,
            full_services=full_services,
            published=published,
            unpublished=unpublished,
            tools=tools,
            ver=ver,
        ),
    }


def main(argv: list[str]) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--check",
        action="store_true",
        help="fail if the committed files differ from what would be generated",
    )
    args = parser.parse_args(argv)

    try:
        outputs = build()
    except GenerationError as exc:
        print(f"LLMS-TXT GENERATION FAILED: {exc}", file=sys.stderr)
        return 1

    if args.check:
        drift = [path for path, content in outputs.items() if not path.is_file() or path.read_text(encoding="utf-8") != content]
        if drift:
            print("LLMS-TXT GATE FAILED:", file=sys.stderr)
            for path in drift:
                state = "missing" if not path.is_file() else "stale"
                print(f"  - {path.relative_to(REPO_ROOT)} is {state}.", file=sys.stderr)
            print(
                "    Run: python3 scripts/generate_llms_txt.py",
                file=sys.stderr,
            )
            return 1
        print(f"OK: llms.txt and llms-full.txt match their sources ({len(outputs)} files).")
        return 0

    STATIC_DIR.mkdir(parents=True, exist_ok=True)
    for path, content in outputs.items():
        path.write_text(content, encoding="utf-8")
        print(f"wrote {path.relative_to(REPO_ROOT)} ({len(content.splitlines())} lines)")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))