feat: initialize llm-security-commons (charter, license, extraction plan)

Data+contract+fixtures repository for runtime-neutral LLM/agent security
detection. Charter is hard: no engine code, no dependencies, no runtime —
JSON data, normative specs and conformance fixtures only.

Scaffolding only; the seed data files land in follow-up commits from
verified source dumps (never from recollection).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0191AKc2qW6tmXDFSx1xn53q
This commit is contained in:
Kjell Tore Guttormsen 2026-08-09 14:29:16 +02:00
commit ef80288c57
6 changed files with 385 additions and 0 deletions

14
.gitignore vendored Normal file
View file

@ -0,0 +1,14 @@
# Operational continuity state — LOCAL-ONLY, never committed.
# Rationale: this repository is published to a public mirror (Forgejo open/), and
# STATE.md must never reach a public surface. It is also vendored by consumers, so a
# committed root STATE.md would land inside every consumer's vendored copy.
/STATE.md
# Local-scoped notes/overrides convention (KTG global): never mirrored.
*.local.md
# Secrets never belong here — this repository is data only.
.env
.env.*
.DS_Store

17
CHANGELOG.md Normal file
View file

@ -0,0 +1,17 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Versioning note: the repository tag versions **the contract** (file set, key names,
case ids, disposition semantics). Each JSON file additionally carries its own
`"version"` field, bumped when that file changes.
## [Unreleased]
## [0.1.0] — 2026-08-09
Initial extraction. Runtime-neutral detection data, normative contracts and a conformance
corpus, extracted from the `llm-security` Node implementation without behaviour change.

140
CLAUDE.md Normal file
View file

@ -0,0 +1,140 @@
# llm-security-commons
## Kontekst
Runtime-nøytral kjerne for LLM/agent-sikkerhetsdeteksjon: detektor-data, normative
kontrakter og en conformance-korpus som **flere uavhengige runtimes** kan kjøre mot og få
**identisk verdikt** fra. Repoet er delt kjerne, ikke et produkt.
Kjente konsumenter (vendorer dette repoet, endrer det ikke):
- `llm-security` — Claude Code-plugin, Node/ESM-scannere.
- et Python-guard-repo — samme deteksjon i en annen runtime.
- en wiki/advisory-flate — konsumerer samme lexicon og mapping.
Å dele én identisk kjerne er hele poenget: to implementasjoner som gir ulikt verdikt på
samme input er per definisjon en bug i én av dem — ikke en meningsforskjell.
## Charter (HARD — bryter du denne, er endringen feil uansett hvor god den er)
**Ingen engine-kode. Ingenting her kjører.**
- ❌ Ingen `.mjs`, `.js`, `.ts`, `.py`, `.sh` som implementerer deteksjon, scanning,
normalisering, scoring eller I/O.
- ❌ Ingen `package.json`, `pyproject.toml`, lockfiler, dependencies, build-steg.
- ❌ Ingen import fra — eller kjennskap til — noe rammeverk, SDK eller runtime.
- ❌ Ingen nettverk, ingen modellkall, ingen tidsavhengighet, ingen tilfeldighet.
Alt her er **offline og deterministisk**.
- ✅ Kun: JSON-data, normative spesifikasjoner (Markdown), og fixtures
(`input` + `expected`).
Regelen finnes fordi kjernen skal være **fork-and-own**: en konsument på en runtime vi
ikke har tenkt på skal kunne vendore dette uten å arve et eneste teknologivalg.
Mønsteret er kopiert fra søsterrepoet `portfolio-optimiser-commons` (samme harde charter:
«nothing here may import/depend on a framework»).
## Stack
Ingen. Data + prosa. Filformater: JSON (data + schema), Markdown (spec), rå tekst
(conformance-input).
## Konvensjoner
### Data (JSON)
- **Hver JSON-fil har et topnivå `"version"`-felt** (semver-streng). Uten unntak.
- Hver JSON-fil har et topnivå `"$comment"` eller `"description"` som sier hva filen er
og hvor dataene kom fra (provenance).
- 2 mellomrom indentering, LF, avsluttende newline. UTF-8 uten BOM.
- Kodepunkter skrives som `"U+200B"`-strenger (lesbare i review), aldri som rå usynlige
tegn i JSON-kilden — bortsett fra i `conformance/*/input.txt`, som per definisjon
inneholder de faktiske tegnene.
- Nøkler er stabile identifikatorer. **Å endre en nøkkel er en breaking change**
konsumenter matcher på dem.
### Spec (Markdown)
- Hver normativ spec har en `**Status: normative**`-markør øverst.
- RFC 2119-språk (MUST / MUST NOT / SHOULD / MAY) i store bokstaver, brukt bevisst.
- Informative dokumenter (`docs/`) har `**Status: informative**` og er aldri ground truth.
### Conformance
- Én katalog per case: `conformance/<case-id>/input.txt` + `conformance/<case-id>/expected.json`.
- `<case-id>` er stabil og beskrivende. **Å endre en case-id er en breaking change.**
- `expected.json` er ground truth. Er en runtime uenig med `expected.json`, er runtimen
feil — med mindre fixturen selv bevises feil, og da endres fixturen i eget commit med
begrunnelse.
### Sikkerhetskritiske tabeller — aldri fra hukommelse
`codepoints/carriers.json` (inkl. homoglyph-map), `signatures/secret-egress.json`,
`signatures/malware-signatures.json` og `signatures/active-content.json` er
**deteksjonsdata**. Et gjettet kodepunkt eller et regex med feil escaping er en stille
falsk negativ — en detektor som ser ut som den virker.
**Disse filene endres KUN fra verifisert kildedata** (dump fra konsument-repo,
Unicode-standarden, publisert leverandør-doc). Aldri fra egen hukommelse, aldri
«fylt ut for konsistens». Kan en oppføring ikke verifiseres: utelat den, eller marker
den eksplisitt uverifisert i `$comment`.
### Behaviour preservation (v0.1.0-invariant)
v0.1.0 er en **ekstraksjon**, ikke en revisjon. Data som er hentet ut av en konsument
skal gi **eksakt samme funn** når konsumenten senere leser dem herfra. Ser du noe du
mener er feil i seed-dataene: **ikke fiks det her**. Dokumentér avviket, send det til
konsumenten via `coord-send`, og la beslutningen tas der dataene er testet.
## Kommandoer
Repoet har ingen build og ingen test-runner (charter). Validering er ad hoc:
```bash
# Alle JSON-filer er velformet
find . -name '*.json' -not -path './.git/*' -print0 | xargs -0 -n1 python3 -m json.tool > /dev/null
# Hver JSON-fil har topnivå "version"
for f in $(find . -name '*.json' -not -path './.git/*' -not -path './conformance/*'); do
python3 -c "import json,sys; d=json.load(open('$f')); sys.exit(0 if 'version' in d else 1)" \
|| echo "MANGLER version: $f"
done
# Hver spec har normativ-markør
grep -L 'Status: normative' spec/*.md
# Charter-guard: ingen kjørbar kode har sneket seg inn
find . -type f \( -name '*.mjs' -o -name '*.js' -o -name '*.ts' -o -name '*.py' -o -name '*.sh' \) \
-not -path './.git/*' | grep . && echo 'CHARTER-BRUDD: kjørbar kode i commons'
```
## Arbeidsflyt
- **Versjonering:** semver på repo-nivå (tag `vX.Y.Z`). Hver JSON-fils `"version"` er
filens egen semver og bumpes når *den filen* endres — de er ikke låst til repo-taggen.
Nytt datafelt eller ny oppføring = minor. Endret/fjernet nøkkel, case-id eller
disposisjon = **major** (konsumenter bryter).
- **Versjonssync før commit:** endrer du en JSON-fil, bump dens `"version"`; endrer du
repoets kontrakt, bump repo-taggen + CHANGELOG.
- **Konsumenter varsles via `coord-send`**, ikke via antakelse. Et repo som vendorer denne
kjernen får ikke vite at kontrakten endret seg med mindre du sier det.
- **Aldri jobb i konsument-repoene fra en økt her.** Vendoring, oppgradering og
behaviour-verifisering skjer i konsumentens egen økt, med konsumentens tester.
- **Forgejo only** (`git.fromaitochitta.com`). Aldri GitHub, aldri `gh` CLI.
- `STATE.md` er LOCAL-ONLY (gitignored) — remote er en offentlig flate.
## Communication patterns
### Linking to local files
When pointing to local files in responses, always use markdown link syntax with a descriptive name:
- Use `[Human-friendly name](file:///absolute/path)` — never bare `file:///...` URLs or autolinks `<file://...>`.
- Always use absolute paths. Never `~/` or relative paths.
- For multiple files, render as a bullet list of named markdown links.
Why: bare `file://` URLs only render the first as clickable across multiple lines. Named markdown links make each entry independently clickable and look cleaner.
Example:
- [Brief](file:///Users/ktg/.../brief.html)
- [Research summary](file:///Users/ktg/.../research/summary.md)

21
LICENSE Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Kjell Tore Guttormsen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

113
README.md Normal file
View file

@ -0,0 +1,113 @@
# llm-security-commons
Runtime-neutral core for LLM and agent security detection: detector data, normative contracts and a conformance corpus that several runtimes can share.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
Detection logic gets reimplemented every time it crosses a language boundary, and the
copies drift: the Node scanner flags a zero-width carrier the Python guard misses, and
nobody notices until an incident. This repository holds the part that should never have
been copied — the pattern tables, the code-point carriers, the calibration thresholds, the
finding contract, and a fixture corpus with expected verdicts — so that two independent
implementations can be held to the same answer on the same input.
It is for anyone building or maintaining a detector for prompt injection, secret egress,
unicode-carrier smuggling or active content in untrusted text, on any runtime.
**It holds no runnable code.** Data, specifications and fixtures only.
## Install
Nothing to install — this repository is **vendored into consumers**, not installed.
As a `git subtree` (recommended: history is preserved and upgrades are a single command):
```bash
git subtree add --prefix vendor/commons \
https://git.fromaitochitta.com/open/llm-security-commons.git v0.1.0 --squash
# later, to move to a newer tag
git subtree pull --prefix vendor/commons \
https://git.fromaitochitta.com/open/llm-security-commons.git v0.2.0 --squash
```
Or pin a tag and copy — `fork-and-own` is an explicitly supported path:
```bash
git clone --depth 1 --branch v0.1.0 \
https://git.fromaitochitta.com/open/llm-security-commons.git
```
Always vendor **a tag**, never `main`. The tag is what a conformance result can be
attributed to.
## Requirements
A JSON parser and the ability to read a text file. That is the entire dependency surface,
and keeping it that small is the point.
## What it does
| Path | Contents |
| --- | --- |
| [`lexicon/injection-lexicon.json`](lexicon/injection-lexicon.json) | Prompt-injection pattern lexicon: instruction-override, exfiltration and role-confusion families with per-pattern ids. |
| [`codepoints/carriers.json`](codepoints/carriers.json) | Invisible and deceptive carriers: zero-width characters, BIDI controls, Unicode Tag block ranges, and the homoglyph map. |
| [`signatures/secret-egress.json`](signatures/secret-egress.json) | Credential and token shapes that must never leave a machine, in a portable regex dialect. |
| [`signatures/malware-signatures.json`](signatures/malware-signatures.json) | Signature set for the malicious-code class (`SIG`). |
| [`signatures/active-content.json`](signatures/active-content.json) | Active content that renders or fetches on its own — Markdown images, links, reference definitions and autolinks, `data:` URIs, active HTML. The EchoLeak class. |
| [`calibration/calibration.json`](calibration/calibration.json) | The numbers a detector must not invent: entropy floors, scan caps, disposition ranks. |
| [`mapping/owasp-map.json`](mapping/owasp-map.json) | Finding-id prefix → OWASP taxonomy entry (LLM / ASI / AST / MCP). |
| [`schema/finding.schema.json`](schema/finding.schema.json) | **Normative.** The finding contract, plus the SARIF and JSONL output profiles. |
| [`spec/decode-pipeline.md`](spec/decode-pipeline.md) | **Normative.** The decode order, in RFC 2119 language. Two runtimes that decode in different orders will disagree on identical input; this is the file that stops that. |
| [`conformance/`](conformance/) | One directory per case: `input.txt` in, `expected.json` out. Ground truth. |
| [`docs/extraction-plan.md`](docs/extraction-plan.md) | Informative: where each file was seeded from, and what v0.1.0 promised. |
Every JSON file carries a top-level `version`. Every normative specification carries a
`Status: normative` marker.
### How a consumer proves it conforms
Run every `conformance/<case>/input.txt` through your detector, serialize the result per
[`schema/finding.schema.json`](schema/finding.schema.json), and compare to
`expected.json`. Disagreement means your runtime is wrong, or the fixture is — and the
fixture only changes in its own commit, with the reason written down.
There is **no CI in this organisation** and nothing runs that comparison automatically. It
runs in each consumer's own test suite, against a pinned tag.
## Non-goals
- **Not a scanner.** There is no engine here, and there will not be one. If you are looking
for something to run, you want a consumer — `llm-security` for Claude Code.
- **Not a framework or a library.** No package manifest, no dependencies, no build.
- **Not a general-purpose Unicode or regex toolkit.** The tables cover what the detection
classes need, not the standard.
- **Not a vulnerability feed.** No CVEs, no advisories, nothing time-sensitive. Everything
here is offline and deterministic.
- **Not a policy engine.** `calibration.json` publishes the thresholds; deciding what to do
when one is crossed belongs to the consumer.
- **Not the place to fix a consumer's behaviour.** Data extracted from an implementation is
kept behaviour-identical on purpose. A disagreement is reported to that implementation
and decided there, where it is tested.
## Known limitations
- **Coverage is the union of what the seed implementations detected**, not of what exists.
A class absent from `conformance/` has not been shown to work anywhere.
- **Regex portability is a real risk.** Pattern data is written for a common subset, but
engines differ (lookbehind, named groups, Unicode property escapes). A consumer whose
engine rejects a pattern must report it rather than silently skip it — a skipped pattern
is an invisible false negative.
- **Fixtures prove agreement, not correctness.** Two runtimes passing the same corpus agree
with each other and with the fixture author. A wrong `expected.json` makes both wrong
identically.
- **The homoglyph map is finite.** Confusable coverage is a long tail; absence from the map
is not evidence a character is safe.
## Changelog
See [CHANGELOG.md](CHANGELOG.md).
## License
MIT — see [LICENSE](LICENSE). Fork-and-own is an intended use, not a tolerated one.

80
docs/extraction-plan.md Normal file
View file

@ -0,0 +1,80 @@
# Extraction plan — v0.1.0
**Status: informative.** This is the plan of record for how this repository came to exist,
copied verbatim (structure preserved, lightly reformatted) from the operator brief that
opened it. It is **not** normative: nothing here constrains a consumer. When it disagrees
with `spec/` or `schema/`, those win.
Origin: **Phase 4 of the `llm-security` v8 plan**, which lives in the sibling repository
`llm-security`. That repository is context only — no session in this repository reads from
or writes to it.
## Charter
No engine code. Only: JSON data, normative specs, and a conformance corpus that several
runtimes (Node in `llm-security`, Python in a guard repo, a wiki) can run against and get
an identical verdict from. The pattern is copied from the sibling repository
`portfolio-optimiser-commons` (hard charter: "nothing here may import/depend on a
framework").
## Layout
```
llm-security-commons/
README.md # charter: data+contract+fixtures only, no engine code
lexicon/injection-lexicon.json
codepoints/carriers.json # zero-width, BIDI, Unicode-Tag ranges, homoglyph map
signatures/secret-egress.json
signatures/malware-signatures.json
signatures/active-content.json # EchoLeak: MD image/link/refdef/autolink, data:, active HTML
calibration/calibration.json # entropy floors, scan caps, disposition ranks
mapping/owasp-map.json # prefix -> LLM/ASI/AST/MCP
schema/finding.schema.json # + SARIF & JSONL profiles. Status: normative
spec/decode-pipeline.md # normative RFC-2119 decode order
conformance/ # {case}/input.txt + {case}/expected.json
STATE.md # LOCAL-ONLY / gitignored (mirror commons convention)
```
Every JSON file carries a top-level `"version"` field. Every spec carries a
`Status: normative` marker.
## v0.1.0 seed sources
`llm-security` is the canonical and richest source. **This repository's sessions have no
read access to it** — content arrives only as an operator-supplied dump. Security-critical
tables (homoglyph map, secret patterns, malware signatures) MUST come from real source
data, never from recollection or inference.
| Target | Seed source in `llm-security` (unless noted) |
|---|---|
| `lexicon/injection-lexicon.json` | `scanners/lib/injection-patterns.mjs` |
| `codepoints/carriers.json` | `scanners/unicode-scanner.mjs` + `scanners/lib/string-utils.mjs` (incl. `HOMOGLYPH_MAP`) |
| `signatures/secret-egress.json` | `knowledge/secrets-patterns.md` — the **18-entry hook table**, NOT the PCRE-flavored agent-consumed variant |
| `signatures/malware-signatures.json` | `knowledge/signatures.json` (the SIG scanner) |
| `signatures/active-content.json` | currently only in a guard repo's `active_content.py`. If unavailable: stub with a version field and a TODO naming the source |
| `calibration/calibration.json` | `scanners/lib/severity.mjs` — thresholds + scanner caps |
| `mapping/owasp-map.json` | `scanners/lib/severity.mjs``OWASP_MAP` (+ 3 sibling maps in the same file) |
| `schema/finding.schema.json` | modelled on `scanners/lib/sarif-formatter.mjs`'s SARIF shape |
| `conformance/` | union of the guard repo's `coverage.py` matrix (126 classes + 4 gaps-must-hold) and `llm-security/examples/` |
## Constraints
- Offline / deterministic only — no network, no model calls inside the data itself.
- Forgejo `open/` — never GitHub.
- MIT license, fork-and-own.
- `STATE.md` is LOCAL-ONLY (gitignored) — same convention as the rest of the polyrepo.
- **Behaviour preservation is the point:** this must not change a single finding in
`llm-security` when it is later consumed from here. That consumption happens in
`llm-security`'s own Phase 5 steps 34 — **not here.**
## Definition of done for v0.1.0
1. Repository initialized, Forgejo remote `open/llm-security-commons`, MIT, `STATE.md`
gitignored.
2. Every file in the layout above present and populated from verified seed data — or
explicitly and visibly stubbed where the source was unavailable.
3. All JSON well-formed, every data file carrying `"version"`, every spec carrying
`Status: normative`.
4. Tagged `v0.1.0` and pushed.
5. A `coord` message sent to `llm-security` announcing that the repository and `v0.1.0`
exist, so Phase 5 step 3 (vendoring) can start from there.