Spec Objects Security Specification
Index of artifacts in this directory.
Open source Repository Open in the app JSON README (API)
About
# Spec Objects Security Specification
## Contents
* [Functional](./functional/index.md) - Functional artifacts.
* [Non Functional](./non-functional/index.md) - Non-functional artifacts.
* [Usecase](./usecase/index.md) - User story artifacts.
* [Integration](./integration/index.md) - Integration artifacts.
* [Stakeholder](./stakeholder/index.md) - Stakeholder artifacts.
* [Spec](./spec.md)
Details
- Kind
- OKF bundles
- Topic
- Files & documents
- Publisher
- agent-ix
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Last push
- 2026-09-04T22:56:38Z
- Repository state
- ativo
- Language
- Python
- License
- AGPL-3.0
- Added
- 2026-09-08 09:04:14
- Updated
- 2026-09-08 09:04:14
- Origin id
agent-ix/spec-objects-security:spec/index.md
README
# 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`](https://github.com/agent-ix/quire-cli) and [`quoin`](https://github.com/agent-ix/quoin) to author and validate Markdown spec artifacts. ## Installing quire-cli `@agent-ix` packages are published to public npm. Install the CLI globally: ```bash 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. ```bash npm install @agent-ix/spec-objects-security ``` ```bash # 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`](https://github.com/agent-ix/quoin) is the spec-domain authoring CLI. Install the module as a plugin, then author and validate: ```bash 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/`): ```bash 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](https://github.com/agent-ix/quire-cli#usage-instructions) for all commands. ## Development This module is a flat-layout Python package (`spec_objects_security`, Python 3.13+) managed with [Poetry](https://python-poetry.org/) and built/published via GitHub Actions to Google Artifact Registry (PyPI-compatible). ```bash 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](./LICENSE).