Spec-as-source is the most ambitious form of spec-driven development, where the specification is the primary maintained artifact and code is regenerated from it. This model treats the spec as the canonical expression of behavior, so versioning, review, and promotion controls apply to the spec itself.
Expanded Definition
Spec-as-source is a stricter spec-driven pattern in which the specification is the maintained system of record, and code is generated from that source rather than hand-edited as the primary artifact. In NHI and agentic systems, this approach is often used for policy-defined behavior, interface contracts, and reproducible control logic where drift between intent and implementation creates risk. It differs from ordinary documentation because the spec is not explanatory material; it is the authoritative input to build, review, promotion, and rollback decisions. That makes governance more important, because changes to the spec can alter runtime behavior across many generated components at once. Definitions vary across vendors, and no single standard governs this yet, so teams should be explicit about what is generated, what is manually edited, and what remains outside the spec boundary. For broader security context, NIST’s NIST Cybersecurity Framework 2.0 is useful for mapping governance and change-control expectations. The most common misapplication is treating prose documentation as spec-as-source, which occurs when engineers still patch generated code by hand after the spec has changed.
Examples and Use Cases
Implementing spec-as-source rigorously often introduces tighter release discipline and regeneration dependencies, requiring organisations to weigh consistency and auditability against slower ad hoc changes.
- API client generation for NHI control planes, where a canonical spec drives consistent authentication flows, schema validation, and retry behavior across services.
- Policy-as-code pipelines for service accounts, where approved spec changes regenerate enforcement logic and reduce manual drift in privilege assignment.
- Agent tool manifests that define allowed actions, input constraints, and escalation paths, then regenerate runtime wrappers from the approved spec.
- Deployment of machine-checked identities or credentials workflows, informed by cases such as ASP.NET machine keys RCE attack, where hidden assumptions in implementation created exploitation paths.
- Security review of hard-coded trust material, similar to Gladinet Hard-Coded Keys RCE Exploitation, where the artifact that should have been authoritative was not the one actually enforced.
Why It Matters in NHI Security
Spec-as-source matters because NHI failures often begin when policy, identity behavior, and implementation diverge. In environments with service accounts, API keys, and agentic execution paths, the authoritative spec can encode least privilege, rotation expectations, and tool access boundaries more reliably than scattered code reviews. That is especially important when organisations struggle with visibility and control: NHIMG reports that only 5.7% of organisations have full visibility into their service accounts, while 97% of NHIs carry excessive privileges, which makes uncontrolled drift far more dangerous. A spec-as-source model can improve traceability, but only if versioning and promotion controls protect the spec itself as the security boundary. It also helps align engineering change management with identity governance, especially when generated artifacts must be recreated after rotation or offboarding events. For NHI lifecycle governance, NHIMG’s Ultimate Guide to NHIs is the clearest reference point. Organisations typically encounter the cost of spec drift only after a service account is abused or a secret is embedded in production behavior, at which point spec-as-source becomes operationally unavoidable to address.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 and OWASP Agentic AI Top 10 address the attack and risk surface, while NIST CSF 2.0, NIST Zero Trust (SP 800-207) and NIST AI RMF set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Non-Human Identity Top 10 | NHI-01 | Spec-as-source reduces drift in NHI definitions, lifecycle, and enforcement paths. |
| OWASP Agentic AI Top 10 | A-04 | Agent tool access and behavior contracts are often defined in source-of-truth specs. |
| NIST CSF 2.0 | PR.IP-1 | Configuration and change management apply when specs drive production code generation. |
| NIST Zero Trust (SP 800-207) | RA-3 | Zero Trust relies on explicit policy expression and continuously validated access decisions. |
| NIST AI RMF | MAP | AI risk mapping benefits from a canonical spec for behavior, inputs, and outputs. |
Treat the spec as the controlled NHI artifact and regenerate implementations from approved versions only.
