@agent-ix/spec-objects-security

spec-objects-security

Filament Module: tier-2 security and identity ObjectTypes (threats, controls, auth flows, secrets, policies)

spec-objects-security is an Agent-IX Filament module: a manifest.yaml plus per-kind authoring skeletons (and frontmatter schemas) that teach the spec tooling a vocabulary of object kinds. It is not a standalone app — it is loaded by quire-cli and quoin to author and validate Markdown spec artifacts.

Installing quire-cli

@agent-ix packages are published to public npm. Install the CLI globally:

npm install -g @agent-ix/quire-cli

See https://github.com/agent-ix/quire-cli#install for details.

Install this module via npm

This module is also published as a config-only npm package: @agent-ix/spec-objects-security. The package root is the Filament module (manifest.yaml + schemas/skeletons), so it works directly as a --module target or via quoin's package: source.

npm install @agent-ix/spec-objects-security

# quoin — resolve the module from npm by name
quoin plugin install package:@agent-ix/spec-objects-security

# or point any tool at the installed package root
quire validate spec/**/*.md --module node_modules/@agent-ix/spec-objects-security

Object types provided

This module adds the following object kinds (frontmatter type: value in parentheses). All kinds are tier-2 embedded ObjectTypes — they require id, title and type in frontmatter plus the kind-specific contract below.

Object	type:	Description
Auth flow	auth_flow	An authentication/login flow, with a Flow section carrying a mermaid diagram of the sequence (e.g. OIDC authorization code flow).
Permission	permission	A single grantable permission, naming the protected resource kind and the verb (action) it grants on it.
Scope	scope	An OAuth/authorization scope, with a Grants section listing the permissions the scope confers.
Role	role	A named role, with a Permissions section listing the permissions bound to it.
Secret	secret	A managed secret (e.g. client secret), with a Rotation section describing how and how often it rotates.
Encryption key	encryption_key	An encryption key, with frontmatter algorithm (cipher) and optional rotation cadence.
Session config	session_config	A session configuration, with a Settings section enumerating the effective session parameters (cookies, timeouts, limits).
Data classification	data_classification	A data sensitivity class, with a Handling section stating the handling requirements for that class.
Trust boundary	trust_boundary	A trust boundary between security zones, with a Boundary section carrying a mermaid diagram of the zones.
Audit event	audit_event	An emitted audit/log event, with an Event Schema section carrying a JSON code block of its payload schema.
CSRF token	csrf_token	A CSRF-protection token, with frontmatter rotation_window (how often a fresh token is issued).
CORS policy	cors_policy	A browser cross-origin policy, with an Origins section enumerating the allowed origins and their rules.
Password policy	password_policy	A password policy, with a Rules section enumerating the enforced password rules.
MFA method	mfa_method	A multi-factor authentication method, with frontmatter kind (method kind) and optional factor (auth factor class).
JWT claim	jwt_claim	A JWT/token claim, with a Schema section carrying a JSON code block of the claim's JSON Schema.
Threat	threat	A threat, with frontmatter stride_category (STRIDE class) and vector (the attack vector).
Control	control	A security control, with a Mappings section mapping it to the threats, risks and standards it addresses.
Risk	risk	A risk-register entry, with frontmatter likelihood and impact qualitative ratings driving its score.
Vulnerability	vulnerability	A vulnerability, with frontmatter severity and optional cve_id linking the public advisory.
Asset	asset	A protected asset, with a Description section describing the asset and why it matters.
Attack surface	attack_surface	An attack surface, with an Entry Points section enumerating the externally reachable entry points.
Policy	policy	A normative security policy, with a Policy section stating the policy text.
Audit finding	audit_finding	A security-audit finding, with a Recommendation section stating the remediation recommendation.

How this module is used

With quoin (recommended)

quoin is the spec-domain authoring CLI. Install the module as a plugin, then author and validate:

quoin plugin install path:../spec-objects-security
quoin catalog list                      # list the kinds this module adds
quoin write . --types threat,control    # scaffold artifacts of these kinds
quoin review                            # validate authored files

With quire-cli directly

Point quire at this module (the package directory holds manifest.yaml and skeletons/):

quire schema threat --module ./spec_objects_security                 # a kind's extraction contract
quire validate spec/**/*.md --module ./spec_objects_security         # structural validation
quire extract <DOC> --module ./spec_objects_security                 # extract structured data

See the quire-cli usage docs for all commands.

Development

This module is a flat-layout Python package (spec_objects_security, Python 3.13+) managed with Poetry and built/published via GitHub Actions to Google Artifact Registry (PyPI-compatible).

make install          # install dependencies in the Poetry venv
make test             # run pytest
make lint             # ruff + black --check
make format           # auto-format (ruff --fix + black)
make build            # build wheel + sdist under dist/
make local-publish    # publish to the local pypi.ix registry
make update-lock      # update poetry.lock
make use-local p=<name> / make use-upstream p=<name>   # swap a dep source

CI: GitHub Actions runs on push, pull_request, and v*.*.* tags — it tests, lints, builds with poetry build, and on tags publishes via twine upload -r internal-pypi. Versioning is dynamic from the Git tag. Required CI config: GCP_SERVICE_ACCOUNT_KEY (secret) plus GCP_REGION, GCP_PROJECT_NAME, GCP_PYPI (variables).

License

AGPL-3.0-or-later — see LICENSE.