| # 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) |
|
|
| ```bash |
| 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: |
|
|
| ```json |
| {"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. |
|
|
