MODEL_CARD.md

Psy 6.9M Model Card

Model

• Name: Psy
• Bundle version: v0.1
• Model type: byte-level, zero-language cyber artifact encoder (classification-only)
• License: Apache-2.0 (see LICENSE)
• Checkpoint: checkpoints/psy_6.9m_encoder.pt
• Encoder parameters: 6,904,064
• Exported encoder SHA256: 2d0a15792bcdfbebfbf689ca0dddd39f9259525bbe9bee9d491289af4e590dbc

Who Psy is for (practical use)

Psy is a tiny (6.9M params / ~27MB / CPU-only / fully offline) instrument that reads a cyber artifact in its raw bytes and returns a coarse severity/verdict. Nothing leaves your machine. Two doors to the same tool:

1 — The defender who's drowning (SOC analyst, solo admin, small team with no SOC). You get buried in CVEs, detection-rule hits, and network flows — more than any human can assess, and the dangerous one hides in the noise. Psy reads each artifact and prioritizes the queue so you look at the scary stuff first. It runs airgapped, on your own hardware — good for orgs that can't send data to a cloud API (defense, healthcare, critical infra, privacy-sensitive) or simply can't afford enterprise tooling.

2 — The vibe coder who's blind (ships fast, AI-assisted, not a security person). You pulled in 400 dependencies you never read and have no idea which CVE is scary or whether a compromised package is beaconing out. Psy is the judgment layer on tools you already run: pipe your npm/pip/cargo audit CVE records in → "fix these 3, ignore the wall of yellow." It reads the bytes so you don't have to understand them — tiny enough to drop in a pre-ship checklist or a git hook.

Honest boundary (this is the feature, not a caveat): Psy is a scorer that sits on top of feeds you already have (audit output, captured flows) — not a one-click "scan my repo" scanner. It prioritizes and flags; it does not decide, fix, or guarantee, and it returns PSY_UNCERTAIN when it isn't sure instead of bluffing. An instrument for a human in the loop, not an oracle.

Quickstart (run it — verified output)

python3 scripts/validate_bundle.py                                   # expect status PASSED (1 network_flow warning)
python3 scripts/run_demo.py --artifact demo_artifacts/rule_ast_sample.jsonl

Feed it a detection-rule AST → Psy reads the bytes and returns one strict-JSON verdict:

{"psy_frame":{"magic":[80,83,89],"version":1,"sender":2,"receiver":1,"intent":5,
              "opcode":69,"confidence":0.8381},
 "status":"PSY_ANOMALY_FOUND",
 "verdict":{"family":"RULE_AST","action":"BLOCK","label":2,"class_index":2,"artifact_type":5,
            "confidence":0.8381,"mode":"encoder_plus_probe_head","head_status":"loaded",
            "status":"PSY_ANOMALY_FOUND","artifact_hash":"e0a7780dd5ad7c080d0ead87f5cace38",
            "embedding_norm":28.4617,"display":"Psy anomaly found."}}

That's the whole contract: bytes in, one honest structured verdict out. (The CVE_RECORD demo returns a confident PSY_UNCERTAIN/ABSTAIN — a real "investigate" call, explained below; NETWORK_FLOW runs encoder-only in v0.1 — see the head table.)

Defensive-Use Statement

Psy is a defensive research instrument. It reads already-structured cyber artifacts (a sanitized CVE record, a detection-rule AST, a network-flow header) and emits a coarse severity/verdict frame. It has no generative, executive, or remediation capability: verified by reading and running the code, there is no code path that generates text, generates code, executes an artifact, patches a system, or emits an exploit. The runtime only encodes an artifact to a 256-dim embedding, applies a small linear probe head, and reports a severity class. It must not be used as, or represented as, a production security scanner, and it cannot detect malware or exploits. Do not feed it untrusted executable content expecting containment — it does not run anything, but it also does not defend anything on its own.

Architecture (as implemented, verified from tensor shapes)

Byte-level pre-LN Transformer encoder backbone.

• 6 transformer layers (MultiheadAttention, 8 heads, batch_first; GELU FFN 256 -> 1024 -> 256)
• Hidden size (d_model): 256
• Byte vocabulary: 257 (byte_emb, shape [257, 256])
• Field vocabulary: 8192 (field_emb, shape [8192, 256], shared across field keys, field values, and seq)
• Artifact-type vocabulary: 8 (type_emb, shape [8, 256])
• No positional embeddings.
• Input assembly per artifact: [ type(1) + field_key + field_val(32) + seq(64) + bytes(512) ] = 609 tokens.
• Pooling: the artifact-type token at position 0 acts as a CLS token; the model returns the pooled [:, 0] vector = a 256-dim embedding.
• Final LayerNorm before pooling.

The exported checkpoint contains only the encoder backbone (77 tensors, 6,904,064 params, loads with 0 missing / 0 unexpected keys via the bundle's load_encoder, which uses weights_only=True and treats any missing/unexpected key as an error). Masked-training prediction heads were stripped at export so the bundle ships Psy purely as the 6.9M artifact-encoder instrument, plus the two small probe heads described below.

Probe Heads (what actually ships)

The encoder is task-agnostic. Per-family severity is produced by a tiny linear probe head (nn.Linear(256, num_classes), loaded strict=True) placed on the pooled embedding, followed by softmax + argmax.

This bundle ships two trained probe heads (CVE_RECORD and RULE_AST are fully functional end-to-end; NETWORK_FLOW is encoder-only in v0.1):

Family	Head file	Shape	SHA256	Ships?
CVE_RECORD	checkpoints/heads/cve_sanitized_head.pt	Linear(256->3)	b6c9cfae96b3b22414e2f956e3cfa657a9160e092652c0cc48eeac14c244760f	Yes
RULE_AST	checkpoints/heads/rule_ast_head.pt	Linear(256->3)	bc6a96c03a987a8819cd055b69828ce71817a5cc94b33e6cedcdbb52d5d64d27	Yes
NETWORK_FLOW	checkpoints/heads/network_flow_head.pt	Linear(256->2)	(not shipped)	No

If a family's head is absent, the runtime does not fabricate a verdict: it runs the encoder only, returns head_status: "probe_head_not_present", mode: "encoder_only", and PSY_UNCERTAIN / ABSTAIN at confidence 0.0.

Inputs

Psy consumes structured JSON cyber artifacts with:

• artifact_type or artifact_family
• payload_bytes_b64 or payload_bytes
• field_ids
• field_values
• seq

Outputs

The runtime emits one strict-JSON status/verdict frame per artifact containing:

• a Psy contact/status frame (magic, version, sender, receiver, intent, opcode, confidence)
• artifact family and artifact hash (BLAKE2b-128 of the canonical JSON)
• encoder statistics (embedding_norm)
• mode (encoder_plus_probe_head or encoder_only), head_status, class_index, label, confidence
• a status + action

Class -> opcode -> action mapping

Probe label	Opcode	Status	Action
0	PSY_SAFE	PSY_SAFE	ALLOW
1	PSY_UNCERTAIN	PSY_UNCERTAIN	ABSTAIN
2	PSY_ANOMALY_FOUND	PSY_ANOMALY_FOUND	BLOCK

Note on the two meanings of PSY_UNCERTAIN: it is emitted both when the probe head confidently predicts the middle (investigate) class (a real, high- confidence label-1 prediction) and when there is no head available (encoder- only). Disambiguate using mode / head_status / confidence, not the status string alone. This is why the CVE demo can read PSY_UNCERTAIN at confidence 0.9996 — it is a confident label-1 (MEDIUM/INVESTIGATE) prediction the opcode layer maps to ABSTAIN, not a malfunction.

What each family does end-to-end (verified by running)

Family	Mode	Demo result	Notes
RULE_AST	encoder + probe head	label 2 -> PSY_ANOMALY_FOUND / BLOCK, conf 0.8381	Decisive verdict path.
CVE_RECORD	encoder + probe head	label 1 -> PSY_UNCERTAIN / ABSTAIN, conf 0.9996	Head runs; demo sample lands on the investigate class.
NETWORK_FLOW	encoder only (no head)	PSY_UNCERTAIN / ABSTAIN, conf 0.0	Head not shipped in v0.1; encoder-only by design.

Probe metrics (sanitized training-run summaries)

These are summaries carried from the local metric log; the full training logs, shards, and held-out reproduction are not included in this bundle. They describe the trained probes, not an in-bundle re-evaluation.

Family	Baseline (majority)	Test accuracy	Macro-F1	Status	Head shipped
CVE_RECORD	0.6424	0.8684	0.7706	SIGNAL	Yes
RULE_AST	0.5129	0.7847	0.7013	SIGNAL	Yes
NETWORK_FLOW	0.9952	1.0000	0.9989	MARGINAL	No

The CVE probe is trained on sanitized records with direct CVSS/severity fields removed, so it reflects structural signal rather than a copied severity field.

Limitations

• Not a production security scanner. Not malware/exploit detection.
• Does not generate code or patches, does not execute artifacts, does not chat.
• Does not contain the training corpus, shards, or logs.
• A scorer on top of existing feeds, not a repo/network scanner — you supply the artifacts.
• Only two of three advertised families produce a probe verdict in v0.1; NETWORK_FLOW ships encoder-only (no head weights).
• NETWORK_FLOW metrics are dominated by extreme class imbalance (train class 0:2 = 896,107:4,327). Test accuracy 1.0 is not meaningful on its own; the family is marked MARGINAL and would require class-wise validation before any head is treated as a real signal. This is the reason its head is held back from v0.1 rather than shipped.
• Probe metrics above are training-run summaries, not reproduced inside the bundle; treat them as reported-not-reverified.

Provenance / integrity

• Verify the encoder: sha256sum checkpoints/psy_6.9m_encoder.pt must equal the SHA above.
• Verify the heads: the two head SHAs above.
• python3 scripts/validate_bundle.py re-derives the param count (must == 6,904,064), checks required files, scans for secrets/non-loopback IPs, and confirms no forbidden path components. Expected result on a clean release: status: PASSED with a single warning for the intentionally-absent network_flow_head.pt.

This isn't only for developers

The two use cases above assume some technical context, but the need isn't limited to people who write code. A nonprofit running a donated laptop fleet, a small business owner handed a vendor's CVE list with no security staff to read it, a student trying to understand what "severity" actually means in a disclosure — none of that requires a job title. The floor to use Psy is a correctly-shaped JSON record, not a background in security or software. If you can get your artifact into that shape (yourself, with a script someone wrote for you, or by asking an AI assistant to format it), Psy will read it the same way for anyone.