Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 28 additions & 20 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,10 @@
"url": "git+https://github.com/agent-ix/spec-objects-security.git"
},
"devDependencies": {
"@agent-ix/quire-cli": "0.45.0",
"@agent-ix/quire-cli": "0.46.0",
"@agent-ix/quoin": "0.30.1",
"@agent-ix/semantic-core": "0.4.4",
"@agent-ix/spec-objects-architecture": "0.12.0",
"@typespec/compiler": "1.15.0",
"@typespec/json-schema": "1.15.0"
}
Expand Down
32 changes: 32 additions & 0 deletions scripts/generate-schemas.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,37 @@ function normalize(schemas, base, moduleFiles, coreBase) {
for (const [name, schema] of schemas) walk(name, schema);
}

/**
* Frontmatter validators compile without the module schema registry (FR-069).
* Keep their closed enum members inline so validation stays offline while the
* regular data schemas can continue to reference the shared enum schemas.
*/
function inlineFrontmatterEnums(schemas) {
const byId = new Map(
schemas.map(([, schema]) => [schema.$id, schema]).filter(([id]) => id),
);
for (const [name, schema] of schemas) {
if (!name.endsWith("Frontmatter.json")) continue;
const visit = (node) => {
if (Array.isArray(node)) {
for (const item of node) visit(item);
return;
}
if (!node || typeof node !== "object") return;
if (typeof node.$ref === "string") {
const target = byId.get(node.$ref);
if (target && Array.isArray(target.enum)) {
delete node.$ref;
node.type = target.type;
node.enum = [...target.enum];
}
}
for (const value of Object.values(node)) visit(value);
};
visit(schema);
}
}

function render(schema) {
return `${JSON.stringify(schema, null, 2)}\n`;
}
Expand All @@ -138,6 +169,7 @@ function emit() {
}
const moduleFiles = new Set(mine.map(([name]) => name));
normalize(mine, base, moduleFiles, semanticCoreBase());
inlineFrontmatterEnums(mine);
const rendered = new Map(mine.map(([name, schema]) => [name, render(schema)]));

return rendered;
Expand Down
5 changes: 5 additions & 0 deletions spec/tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ the Python package only: neither Node script is measured by it.
| NFR-003 | NFR-003-AC-1..2, NFR-003-M-1..2 | TC-204, TC-205 | ✅ |
| FR-023 | FR-023-AC-1..10 | TC-206..TC-217 | ✅ AC-7 is an inspection |
| FR-024 | FR-024-AC-1..7 | TC-220..TC-223 | ✅ |
| FR-025 | FR-025-AC-8..9, FR-025-AC-11 | TC-244..TC-247 | 🚧 AC-11 starter-rule enum coverage remains with PLAT-1540; other FR-025 criteria remain with their owning tickets |
| NFR-004 | NFR-004-AC-1..3, NFR-004-M-1..2 | TC-207, TC-211, TC-213, TC-214 | ✅ |
| FR-017 | FR-017-AC-1..7 | TC-175..TC-186 | ✅ `quire clauses` loads strictly and cannot load the real module (the object-type edges come from another module), so TC-181, TC-183, TC-185 and TC-186 evaluate a module that holds only the set files |
| FR-026 | FR-026-AC-1..7, FR-026-AC-9..10 | TC-224..TC-236, TC-242..TC-243 | ✅ |
Expand Down Expand Up @@ -366,6 +367,10 @@ the Python package only: neither Node script is measured by it.
| TC-241 | The risk skeleton states `decision: undecided` | Unit | P0 | FR-027-AC-6 | ✅ |
| TC-242 | An empty `## Out of scope` section fails validation naming the section | Integration | P0 | FR-026-AC-6 | ✅ |
| TC-243 | `semantic.exports` contains twenty-six types including `threat_model` | Unit | P0 | FR-026-AC-10 | ✅ |
| TC-244 | Safeguard and frontmatter schemas admit the declared non-empty unique safeguard lists and reject undeclared values | Unit | P0 | FR-025-AC-8, FR-025-AC-11 | ✅ |
| TC-245 | Control safeguards are optional authored frontmatter, are extracted when present, and the skeleton validates | Integration | P0 | FR-025-AC-8, FR-025-AC-9 | ✅ |
| TC-246 | A control protects a connection and a data sink without a disallowed-target diagnostic | Integration | P0 | FR-025-AC-9 | ✅ |
| TC-247 | Control and data-classification manifests reference their open frontmatter schemas and declare the field locators | Unit | P0 | FR-025-AC-9, FR-025-AC-11 | ✅ |

## Test Environment

Expand Down
8 changes: 7 additions & 1 deletion spec_objects_security/manifest.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,7 @@ object_types:
after_heading: Invariants
required: false
- name: data_classification
frontmatter_schema_ref: schemas/DataClassificationFrontmatter.json
allowed_links:
classifies: [persistable, externally-exposed, sensitive]
references: [data_classification]
Expand Down Expand Up @@ -470,10 +471,11 @@ object_types:
after_heading: Properties
required: false
- name: control
frontmatter_schema_ref: schemas/ControlFrontmatter.json
allowed_links:
mitigates: [threat, risk, vulnerability, hazard, failure_mode]
implements: [policy]
protects: [externally-exposed, asset]
protects: [externally-exposed, asset, connection, data_sink]
data_schema:
schema: schemas/Control.json
body_extraction:
Expand All @@ -490,6 +492,10 @@ object_types:
from: section_body
after_heading: Effectiveness
required: false
safeguards:
from: frontmatter_field
path: [safeguards]
required: false
# FR-005: the typed `## Properties` table the
# semantic layer reads. Optional, so existing artifacts stay valid.
properties:
Expand Down
8 changes: 8 additions & 0 deletions spec_objects_security/schemas/Control.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,14 @@
"effectiveness": {
"$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/ControlEffectiveness.json"
},
"safeguards": {
"type": "array",
"items": {
"$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/Safeguard.json"
},
"minItems": 1,
"uniqueItems": true
},
"mitigates": {
"type": "array",
"items": {
Expand Down
25 changes: 25 additions & 0 deletions spec_objects_security/schemas/ControlFrontmatter.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/ControlFrontmatter.json",
"type": "object",
"properties": {
"safeguards": {
"type": "array",
"items": {
"type": "string",
"enum": [
"encrypt-in-transit",
"encrypt-at-rest",
"anonymize",
"pseudonymize",
"obtain-consent",
"restrict-region",
"validate-before-display"
]
},
"minItems": 1,
"uniqueItems": true
}
},
"description": "Frontmatter keys authored on a control document."
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/DataClassificationFrontmatter.json",
"type": "object",
"properties": {
"regulated_categories": {
"type": "array",
"items": {
"type": "string",
"enum": [
"health",
"personal",
"financial"
]
},
"minItems": 1,
"uniqueItems": true
}
},
"description": "Frontmatter keys authored on a data-classification document."
}
15 changes: 15 additions & 0 deletions spec_objects_security/schemas/Safeguard.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/Safeguard.json",
"type": "string",
"enum": [
"encrypt-in-transit",
"encrypt-at-rest",
"anonymize",
"pseudonymize",
"obtain-consent",
"restrict-region",
"validate-before-display"
],
"description": "Safeguards a person may state for a control."
}
2 changes: 2 additions & 0 deletions spec_objects_security/skeletons/control.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,12 @@ id: CTRL-001
title: "RefreshTokenRotation"
type: control
object: control
safeguards: [encrypt-in-transit]
---
<!-- control authoring skeleton (spec-objects-security). Fill every section with
substantive content. Contract (manifest body_extraction asserts):
- Frontmatter MUST carry id, title, type: control, object: control.
- Optional safeguards are the seven values in the Safeguard vocabulary.
- "## Mappings" (H2, optional): a Set / Clause table, one row per clause
of a clause set this control answers. Set is the key
authority/id@version; no standard text belongs here. Threats and risks
Expand Down
12 changes: 12 additions & 0 deletions tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,18 @@ def engine_tool(name: str) -> str:
return path


def validation_module_args(security_module: pathlib.Path | None = None) -> list[str]:
"""Load this module with its cross-module object types and edge registries."""
architecture_module = (
pathlib.Path(__file__).resolve().parent.parent
/ "node_modules"
/ "@agent-ix"
/ "spec-objects-architecture"
)
modules = [security_module or PACKAGE_ROOT, architecture_module]
return [arg for module in modules for arg in ("--module", str(module))]


PACKAGE_ROOT = REPO_ROOT / "spec_objects_security"
MANIFEST_PATH = PACKAGE_ROOT / "manifest.yaml"
SCHEMAS_DIR = PACKAGE_ROOT / "schemas"
Expand Down
15 changes: 12 additions & 3 deletions tests/test_clause_sets.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
from __future__ import annotations

import json
import os
import pathlib
import shutil
import subprocess
Expand Down Expand Up @@ -278,11 +277,21 @@ def test_the_module_data_files_ship_in_the_wheel_and_the_npm_tarball():
with zipfile.ZipFile(next(pathlib.Path(tmp).glob("*.whl"))) as archive:
wheel = set(archive.namelist())
packed = subprocess.run(
["npm", "pack", "--pack-destination", tmp],
[
"npm",
"pack",
"--pack-destination",
tmp,
"--userconfig",
"/dev/null",
"--cache",
tmp,
"--registry",
"https://registry.npmjs.org/",
],
cwd=str(REPO_ROOT),
capture_output=True,
text=True,
env={**os.environ, "npm_config_registry": "https://registry.npmjs.org/"},
)
assert packed.returncode == 0, packed.stderr
with tarfile.open(next(pathlib.Path(tmp).glob("*.tgz"))) as archive:
Expand Down
Loading
Loading