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.

chore(mcp): add registry descriptors and a GitHub social preview card (#1533)

Beenu Arora2a5ce8404aa9
diff --git a/apps/docs/docs/integrations/mcp.md b/apps/docs/docs/integrations/mcp.md
index 8318543d9..906ca237d 100644
--- a/apps/docs/docs/integrations/mcp.md
+++ b/apps/docs/docs/integrations/mcp.md
@@ -227,6 +227,29 @@ node dist/index.js doctor
**The config file is malformed.** The installer refuses to overwrite a config it can't parse, to avoid clobbering hand-edits. Fix or back up the file, then re-run.
+## Registry listings
+
+Directory sites index MCP servers from a descriptor committed next to the code rather than by scraping the repository. AiSOC ships two:
+
+| File | Read by | What it carries |
+|---|---|---|
+| [`services/mcp/server.json`](https://github.com/beenuar/AiSOC/blob/main/services/mcp/server.json) | the [official MCP registry](https://registry.modelcontextprotocol.io) | Name (`io.github.beenuar/aisoc`), description, version, repository and icon. |
+| `glama.json` (repository root) | [Glama](https://glama.ai/mcp/servers) | The GitHub accounts permitted to maintain the listing. |
+
+**AiSOC is not listed in the MCP registry yet, and the reason is the npm packaging status above rather than a missing descriptor.** The registry stores metadata only — it never hosts the artifact — so a listing has to name a package a client can actually install. It also verifies that whoever publishes the listing owns that package: for npm it reads an `mcpName` field out of the published `package.json` and requires it to equal the server name. `services/mcp/package.json` already declares `"mcpName": "io.github.beenuar/aisoc"`, so that check will pass the moment the package exists; what is missing is the package. Until then `server.json` deliberately declares no `packages` entry, because a listing pointing at an unresolvable package is worse for a reader than no listing.
+
+Once `@aisoc/mcp` is on npm, listing it is a short follow-up: add a `packages` entry naming the published version, then
+
+```bash
+brew install mcp-publisher # or download the release binary
+mcp-publisher login github
+cd services/mcp && mcp-publisher publish
+```
+
+`mcp-publisher validate` checks `server.json` without publishing, and is worth running first.
+
+Nothing in a registry listing changes how the server is installed by hand — the source build above keeps working, and an entry in a directory is discovery, not a new install path.
+
## Source & contributions
The package source lives in [`services/mcp`](https://github.com/beenuar/AiSOC/tree/main/services/mcp). Tests, tool definitions, and the installer are all there. PRs welcome — the contract tests in [`tests/tools.test.ts`](https://github.com/beenuar/AiSOC/blob/main/services/mcp/tests/tools.test.ts) will tell you immediately if you forget metadata, ordering, or naming conventions on a new tool.
diff --git a/apps/docs/static/img/aisoc-github-social-preview.png b/apps/docs/static/img/aisoc-github-social-preview.png
new file mode 100644
index 000000000..681173567
Binary files /dev/null and b/apps/docs/static/img/aisoc-github-social-preview.png differ
diff --git a/apps/docs/static/img/aisoc-github-social-preview.svg b/apps/docs/static/img/aisoc-github-social-preview.svg
new file mode 100644
index 000000000..75c70534b
--- /dev/null
+++ b/apps/docs/static/img/aisoc-github-social-preview.svg
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Source for aisoc-github-social-preview.png, the repository's GitHub social
+ preview (Settings -> General -> Social preview).
+
+ 1280x640 rather than the 1200x630 of aisoc-social-card.png: GitHub states
+ 1280x640 for this field and renders it in link unfurls at a fraction of
+ that size, so the two cards are deliberately separate files and this one
+ carries less text at a larger size.
+
+ Regenerate by screenshotting this file in a headless browser at its exact
+ pixel size, which is also how a crawler will rasterise it:
+
+ chrome --headless --window-size=1280,640 \
+ --default-background-color=00000000 \
+ --screenshot=apps/docs/static/img/aisoc-github-social-preview.png \
+ apps/docs/static/img/aisoc-github-social-preview.svg
+
+ Not `magick`, deliberately. ImageMagick renders this file's text only when
+ it was built with a Freetype or ghostscript delegate; without one it prints
+ "non-conforming drawing primitive definition `text'" and writes a card with
+ every word missing. The sibling aisoc-social-card.svg still documents the
+ `magick` form and is subject to the same trap.
+
+ Deliberately carries no counts, metrics, logos or names other than this
+ project's own. A card is cached by crawlers for a long time and cannot be
+ regenerated by a gate, so any number baked into it would become a stale
+ claim on a surface nobody re-reads. Every capability named here is one the
+ tree implements: fusion is services/fusion, agent triage is
+ services/agents, and the decision ledger is what aisoc_replay_decision
+ reads back.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640">
+ <defs>
+ <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+ <stop offset="0%" stop-color="#0b1220"/>
+ <stop offset="100%" stop-color="#111c33"/>
+ </linearGradient>
+ </defs>
+
+ <rect width="1280" height="640" fill="url(#bg)"/>
+ <rect x="0" y="0" width="12" height="640" fill="#2563eb"/>
+
+ <!-- logo mark, matching img/logo.svg -->
+ <rect x="100" y="128" width="104" height="104" rx="16" fill="#2563eb"/>
+ <text x="152" y="203" font-family="Helvetica, Arial, sans-serif" font-size="64"
+ font-weight="bold" fill="#ffffff" text-anchor="middle">A</text>
+
+ <!-- wordmark -->
+ <text x="236" y="212" font-family="Helvetica, Arial, sans-serif" font-size="112"
+ font-weight="bold" fill="#ffffff" letter-spacing="-2">AiSOC</text>
+
+ <!-- value proposition -->
+ <text x="104" y="348" font-family="Helvetica, Arial, sans-serif" font-size="48"
+ fill="#93b4f5">Open-source AI Security Operations Center</text>
+
+ <!-- what it actually does -->
+ <text x="104" y="424" font-family="Helvetica, Arial, sans-serif" font-size="32"
+ fill="#c3cede">Alert fusion, agent triage, and a replayable decision ledger.</text>
+
+ <!-- rule -->
+ <rect x="104" y="512" width="1072" height="1" fill="#26344d"/>
+
+ <!-- footer -->
+ <text x="104" y="566" font-family="Helvetica, Arial, sans-serif" font-size="27"
+ fill="#8fa0bb">MIT licensed &#183; self-hostable</text>
+ <text x="1176" y="566" text-anchor="end" font-family="Helvetica, Arial, sans-serif"
+ font-size="27" fill="#8fa0bb">github.com/beenuar/AiSOC</text>
+</svg>
diff --git a/docs/remediation/discoverability-descriptors.md b/docs/remediation/discoverability-descriptors.md
new file mode 100644
index 000000000..7d33624a0
--- /dev/null
+++ b/docs/remediation/discoverability-descriptors.md
@@ -0,0 +1,310 @@
+# Discoverability — registry descriptors and the social preview
+
+Scope: `services/mcp/**`, root-level registry descriptors, and one static
+image. Two items from an external audit, both of whose premises turned out to
+be partly wrong. What follows records what is actually true, measured on
+2026-10-28, and what is left — every remaining step is blocked on an account
+or a credential that no commit can supply.
+
+Nothing here changes how the MCP server runs. A descriptor is how a directory
+site indexes the server; an unlisted server still works from a source build.
+
+---
+
+## Item 1 — MCP registry descriptors
+
+### What the audit said, and what is true
+
+The audit reported `services/mcp/server.json` as **not found**. It exists, and
+it is valid.
+
+| Audit claim | Verified state |
+|---|---|
+| `server.json` not found | **Present** at `services/mcp/server.json` and schema-valid. |
+| It declares no `packages` and no `remotes`, so the registry would reject it | The first half is true; **the rejection is not**. Neither the JSON Schema nor the registry's semantic validator requires either field. |
+| `io.github.beenuar/aisoc` is unpublished | **Confirmed.** |
+| `smithery.yaml` and `glama.json` are absent | **Confirmed.** |
+
+Validation evidence, against the schema the file itself names:
+
+```
+$ curl -s https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json
+HTTP 200, 22090 bytes
+$ jsonschema Draft202012Validator(schema).iter_errors(server.json)
+errors: 0 → VALID
+```
+
+The schema's only required properties are `name`, `description` and `version`
+(`definitions.ServerDetail.required`). The registry's semantic validator
+(`internal/validators/validators.go` in `modelcontextprotocol/registry`)
+iterates `Packages` and `Remotes` and validates each entry it finds; it has no
+"at least one" rule. So the file would not be *rejected*.
+
+It would, however, be **useless**, which is the real defect and why the item
+still stands: a listing with neither a package nor a remote gives a client
+nothing to install. Of 100 servers sampled from the live registry, **0** had
+neither — 92 carry `remotes`, 10 carry `packages`.
+
+### The true publication state of the MCP artefact
+
+Read from the registries, not from a workflow. `AGENTS.md` is explicit that a
+green workflow is not evidence of publication.
+
+| Distribution channel | Declared where | Registry answer | State |
+|---|---|---|---|
+| npm `@aisoc/mcp` | `release.yml` `npm-publish` matrix | `registry.npmjs.org/@aisoc%2Fmcp` → **HTTP 404** | **Not published** |
+| OCI `ghcr.io/beenuar/aisoc-mcp` | nothing | GHCR v2 tags list → **HTTP 403** | **Does not exist** |
+| OCI `ghcr.io/beenuar/aisoc-mcp-server` | nothing | GHCR v2 tags list → **HTTP 403** | **Does not exist** |
+| MCP registry `io.github.beenuar/aisoc` | `services/mcp/server.json` | `/v0/servers?search=aisoc` → 200, no matching entry | **Not listed** |
+
+Two notes on reading those answers, because both have misled before:
+
+- **A GHCR 403 is ambiguous on its own** and `AGENTS.md` warns it reads as a
+ visibility problem that is not one. It was disambiguated with a control:
+ `ghcr.io/beenuar/aisoc-core-api` answers the same anonymous request with
+ **200 and a full tag list**. A published package is readable; these two are
+ not there. Corroborated structurally — the MCP server appears in **no**
+ entry of the `publish-images.yml` build or merge matrix, and both
+ `docker-compose.yml` and `infra/helm/aisoc/values.yaml` already carry
+ comments saying the image is built locally precisely because no
+ `ghcr.io/beenuar/aisoc-mcp` package has been published.
+- **The registry search for `aisoc` is not empty**, which is a trap. It returns
+ `com.realestateaisociety/follow-up-boss` — an unrelated server matching on
+ the substring inside "realestateaisociety". An exact-name query returns
+ `{"servers":[],"metadata":{"count":0}}`.
+
+So the npm path is the live one: wired in `release.yml`, built and packed on
+every tag, with only the upload gated on a credential that does not exist. The
+OCI path would need a publishing job that nobody has written.
+
+### What changed in this branch
+
+**`services/mcp/package.json` — added `"mcpName": "io.github.beenuar/aisoc"`.**
+
+This is the registry's npm ownership check, and it is the one prerequisite that
+can be satisfied today. Per the registry's package-type documentation, it
+verifies ownership of an npm package by reading `mcpName` from the published
+`package.json` and requiring it to equal the `name` in `server.json`. Without
+it, `mcp-publisher publish` fails ownership verification even after the package
+exists. The field must be in the package *as published*, so it has to be
+committed before the npm upload, not after.
+
+The equivalent for the other channels, recorded so nobody has to re-derive it:
+PyPI, NuGet and Cargo use an `mcp-name: <server name>` string in the package
+README; OCI uses an `io.modelcontextprotocol.server.name` image label. No OCI
+label was added here, because nothing publishes that image and a label no
+publisher reads is not a prerequisite, it is decoration.
+
+**`glama.json` at the repository root — added.** Validated against the schema it
+names:
+
+```
+$ curl -s https://glama.ai/mcp/schemas/server.json
+HTTP 200, 345 bytes, draft-07
+$ jsonschema Draft7Validator(schema).iter_errors(glama.json)
+errors: 0 → VALID
+```
+
+The schema has exactly one property, `maintainers`, an array of unique GitHub
+usernames, and it is required. The value is taken from `.github/CODEOWNERS`,
+which assigns `*` to `@beenuar`, rather than guessed. Root placement was
+confirmed against ten real repositories carrying the file; all ten have it at
+the root.
+
+**`server.json` — deliberately unchanged.** No `packages` entry was invented.
+There is no published artefact to name, and a descriptor pointing at a package
+that 404s is worse than one that is openly incomplete.
+
+That is not merely a judgement call here — **the repository already enforces
+it**, which is worth knowing before anyone "helpfully" adds the entry.
+`services/mcp/tests/registry.test.ts` asserts that an empty `packages` and the
+"ready, unpublished" line in `services/mcp/README.md` move together: add a
+package entry while the README still says the package is unpublished and the
+test fails, and vice versa. The same file already asserts the version
+agreement this work was asked to check for — `expect(manifest.version).toBe(
+pkg.version)` — so no new gate was needed, and none was written. It also caps
+`description` at the registry's 100 characters and pins the schema URL.
+
+All 8 of its cases pass with the `mcpName` addition, as do all 167 tests across
+the 13 files in `services/mcp/tests/`.
+
+### `smithery.yaml` — not added, and why
+
+The audit asked for one. It is not in this branch, because Smithery no longer
+documents the file and writing one would mean guessing at fields.
+
+Evidence. Smithery is now part of Arcade.dev and its documentation was
+restructured; the page that used to document the file,
+`smithery.ai/docs/build/project-config`, now returns **404**, as do
+`/docs/config`, `/docs/deployments` and `/schemas/smithery.yaml`. All 59 pages
+listed in `smithery.ai/docs/llms.txt` were fetched — 11,809 lines — and the
+string `smithery.yaml` appears **0 times**, as do `startCommand` and
+`runtime: typescript`.
+
+The shipped CLI tells the same story from the other side. `@smithery/cli`
+4.11.1 does still read a `smithery.yaml` from the working directory, but only
+to pull an optional `name` string used to pre-fill a prompt; publishing itself
+refuses anything that is not a URL or a bundle (`publish target must be an MCP
+server URL or .mcpb bundle`). The file is a prompt hint, not a configuration
+format.
+
+Smithery's two current paths and how they sit against this project:
+
+- **URL** — Smithery's gateway proxies to a public HTTPS streamable-HTTP
+ endpoint. AiSOC is self-hosted and operates no public MCP endpoint, so there
+ is no URL to register. This is an architectural mismatch, not a missing
+ credential, and it should not be "fixed" by standing one up casually: the MCP
+ server is a standing read path into a tenant's alerts and event lake, which
+ is why `docker-compose.yml` puts it behind its own opt-in profile.
+- **MCPB bundle** — a `.mcpb` of the local stdio server, uploaded through
+ Smithery's flow. This one *is* applicable and is the route to take if a
+ Smithery listing is wanted. It needs a bundle build that does not exist yet
+ and a Smithery account.
+
+Recorded as refused with reasons rather than shipped, on the same principle the
+detection corpus uses.
+
+### Remaining steps, who runs them, and what each is blocked on
+
+All three are account actions. None can be done from a commit.
+
+**1. Publish `@aisoc/mcp` to npm.** *Blocked on: an npm credential.*
+Owner action. The pipeline exists — `release.yml` builds and packs the package
+on every tag and gates only the upload, on `secrets.NPM_TOKEN`. The first
+upload of a never-published package must use a token, because npm's trusted
+publishing is configured on a package's settings page and a package that does
+not exist has no settings page. So: create the `@aisoc` scope on npm, mint a
+publish token, set `NPM_TOKEN` in repository secrets, and cut a release. After
+the first upload, set the `AISOC_NPM_TRUSTED_PUBLISHING` repository variable to
+`true` and the token can be removed.
+
+Verify at the registry, not in the workflow log:
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/@aisoc%2Fmcp
+# 200 means published; 404 means it is not, whatever the run says
+```
+
+**2. List the server in the MCP registry.** *Blocked on: step 1, then a GitHub
+device-code login.* Once npm serves the package, add a `packages` entry to
+`services/mcp/server.json` naming the exact published version — the registry
+rejects ranges — of the shape:
+
+```json
+"packages": [
+ {
+ "registryType": "npm",
+ "identifier": "@aisoc/mcp",
+ "version": "0.1.0",
+ "transport": { "type": "stdio" }
+ }
+]
+```
+
+then, from a machine logged in as a GitHub account with write access to this
+repository:
+
+```bash
+brew install mcp-publisher # or the release binary from the registry repo
+mcp-publisher login github # device-code flow
+cd services/mcp
+mcp-publisher validate # checks server.json without publishing
+mcp-publisher publish
+```
+
+Verify:
+
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0/servers?search=io.github.beenuar/aisoc'
+# currently {"servers":[],"metadata":{"count":0}}
+```
+
+**3. Optional — a Smithery listing.** *Blocked on: an MCPB bundle build and a
+Smithery account.* See the section above for why the URL route does not apply.
+
+### Not done here, and why
+
+**No version gate was added**, because one already exists and is better placed
+than anything that would have been written: `services/mcp/tests/registry.test.ts`
+asserts `server.json` and `package.json` agree, and runs in the `services/mcp`
+leg of `ci.yml`. `check_release_policy.py` was checked and does *not* cover
+this — it binds `VERSION` to `apps/web/package.json` only, and nothing in
+`scripts/` reads `server.json` at all — so the obvious place to look is the
+wrong one. Adding a second assertion in `scripts/` would have duplicated a
+working check in a directory another branch currently owns.
+
+One adjacent observation, not in scope: the regeneration command recorded in
+`apps/docs/static/img/aisoc-social-card.svg` cannot run on a machine whose
+ImageMagick has no Freetype or ghostscript delegate. It does not fail cleanly —
+it emits `non-conforming drawing primitive definition 'text'` and drops every
+text element, so a card regenerated that way loses all its wording while still
+producing a plausible-looking file. The new card is rendered with headless
+Chromium instead — faithful, and what a crawler effectively uses — and its own
+source comment records that command and the reason.
+
+---
+
+## Item 2 — GitHub social preview
+
+The repository has no custom social preview (`usesCustomOpenGraphImage` is
+`false`), so links to it unfurl with the generic owner-avatar card.
+
+**There is no API for this field.** It is Settings → General → Social preview
+in the web UI, and only the repository owner can set it. This item is therefore
+**owner action, and is not done.** Nothing in this branch makes the preview
+live, and it should not be reported as live.
+
+### What is committed
+
+`apps/docs/static/img/aisoc-github-social-preview.png` — 1280x640, the size
+GitHub specifies for this field, with its source alongside it as
+`aisoc-github-social-preview.svg`.
+
+It is a separate file from the existing `aisoc-social-card.png` rather than a
+resize of it: that one is 1200x630 and is wired into `docusaurus.config.ts` as
+the docs site's Open Graph image, and GitHub renders this card much smaller in
+link unfurls, so it carries less text at a larger size.
+
+Content is the wordmark, the logo mark from `img/logo.svg`, one value
+proposition, one line naming what the system does, and a footer. The palette is
+lifted from the existing card: background `#0b1220` → `#111c33`, accent
+`#2563eb`, headline `#93b4f5`, body `#c3cede`, footer `#8fa0bb`.
+
+It carries no metrics, no fabricated logos, no customer names, no testimonials
+and no third-party product names — the same discipline the existing card's
+source comment records, and for the same reason: a crawler caches a card for a
+long time and no gate can regenerate it, so a number baked into it becomes a
+stale claim on a surface nobody re-reads. Each capability named is one the tree
+implements: fusion is `services/fusion`, agent triage is `services/agents`, and
+the replayable decision ledger is what `aisoc_replay_decision` reads back.
+
+Legibility was checked by rendering the card down to 320x160, roughly what a
+chat unfurl shows; the wordmark and the value proposition stay readable.
+
+### The instruction for the owner
+
+> Go to <https://github.com/beenuar/AiSOC/settings> → General → Social preview →
+> Edit → Upload an image, and upload
+> `apps/docs/static/img/aisoc-github-social-preview.png` from a checkout of this
+> branch.
+
+Confirm it took with:
+
+```bash
+gh api repos/beenuar/AiSOC --jq '.usesCustomOpenGraphImage'
+# false today; true once the upload succeeds
+```
+
+---
+
+## Verification summary
+
+| Check | Result |
+|---|---|
+| `server.json` against `server.schema.json` (2025-12-11) | 0 errors, valid |
+| `glama.json` against `glama.ai/mcp/schemas/server.json` (draft-07) | 0 errors, valid |
+| Every URL added by this branch | fetched, all 200 |
+| npm `@aisoc/mcp` | 404, not published |
+| GHCR `aisoc-mcp` / `aisoc-mcp-server` | 403, absent (control `aisoc-core-api` → 200) |
+| MCP registry `io.github.beenuar/aisoc` | absent, count 0 |
+| Social preview PNG | 1280x640, legible at 320x160 |
diff --git a/glama.json b/glama.json
new file mode 100644
index 000000000..01543bee9
--- /dev/null
+++ b/glama.json
@@ -0,0 +1,4 @@
+{
+ "$schema": "https://glama.ai/mcp/schemas/server.json",
+ "maintainers": ["beenuar"]
+}
diff --git a/services/mcp/package.json b/services/mcp/package.json
index c7d01701e..8386d7689 100644
--- a/services/mcp/package.json
+++ b/services/mcp/package.json
@@ -2,6 +2,7 @@
"name": "@aisoc/mcp",
"version": "0.1.0",
"description": "MCP server that exposes AiSOC (alerts, cases, agent investigations, the decision ledger) to Claude Desktop, Cursor, Cody, Continue, and any MCP-aware agent.",
+ "mcpName": "io.github.beenuar/aisoc",
"keywords": [
"aisoc",
"mcp",