Descriptor JSON is a serialised representation of schema definitions used by reflection-based tooling to load or rebuild types dynamically. It is convenient for automation, but security teams should treat it as a code-input artifact whenever the application can execute generated logic from it.
Expanded Definition
Descriptor JSON is a serialised schema representation used by reflection-based tooling to inspect, load, or reconstruct types at runtime. In NHI and agentic systems, that makes it more than a convenience format: it can become an execution-adjacent input that influences how code paths, objects, or tool interfaces are materialised.
That distinction matters because a descriptor often sits between static code and dynamic behaviour. If an application trusts a descriptor to generate classes, bind methods, or infer privileges, the file is effectively part of the application’s control plane. Security teams should therefore assess it using the same caution applied to other code-input artifacts, alongside guidance from the NIST Cybersecurity Framework 2.0.
Definitions vary across vendors, because some ecosystems treat descriptor JSON as passive metadata while others allow it to drive runtime code generation. The most common misapplication is treating it as harmless configuration when the application can execute generated logic from it.
Examples and Use Cases
Implementing Descriptor JSON rigorously often introduces validation and versioning overhead, requiring organisations to weigh faster automation against tighter trust boundaries.
- A service registry exports descriptor JSON so an AI agent can discover callable tools without hardcoding interface details. The descriptor must be authenticated and schema-checked before ingestion.
- Reflection-based middleware uses descriptor JSON to rebuild message types in a CI/CD pipeline. If the pipeline accepts untrusted descriptors, it can compile or dispatch unsafe logic.
- A plugin framework reads descriptor JSON to load third-party extensions. Security review should treat the file as an input to code loading, not as documentation.
- An internal platform stores schema descriptors for service accounts and API-driven workflows. That model is safer when paired with the lifecycle and governance practices described in Ultimate Guide to NHIs.
- Teams using dynamic API clients should compare descriptor handling against the trust assumptions in the NIST Cybersecurity Framework 2.0 so schema changes do not become hidden execution paths.
In practice, Descriptor JSON becomes most sensitive when it is fetched from remote locations, generated by another agent, or accepted from tenants or partners without strong provenance checks.
Why It Matters in NHI Security
Descriptor JSON is important because it can shape how non-human identities are interpreted, provisioned, or allowed to act. If a descriptor alters method bindings, tool declarations, or schema expectations, it can indirectly expand privilege or create injection opportunities in automation pipelines. That risk is especially relevant in environments already struggling with identity governance: NHI Management Group reports that 97% of NHIs carry excessive privileges, which means even small trust mistakes can have outsized impact.
Security practitioners should therefore protect descriptor files with integrity controls, source authentication, change review, and strict allowlisting of fields that affect execution. They should also separate machine-readable metadata from executable logic wherever possible, and reject descriptors that attempt to redefine trust boundaries after deployment. The governance lesson is simple: if a descriptor can influence what an identity or agent is allowed to do, it deserves controls similar to other privileged inputs.
Organisations typically encounter the operational cost of Descriptor JSON only after a malformed or malicious descriptor has already caused unsafe code generation, at which point the term 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 | Descriptor JSON can alter NHI behaviour when it drives dynamic loading or schema trust decisions. |
| OWASP Agentic AI Top 10 | A1 | Agentic tooling may use descriptors as execution inputs for tools and generated logic. |
| NIST CSF 2.0 | PR.DS-6 | Serialized schema artifacts need integrity protection when they influence system behavior. |
| NIST Zero Trust (SP 800-207) | Zero Trust requires continuous validation of inputs, including dynamic schema artifacts. | |
| NIST AI RMF | AI systems using descriptors should manage data and model-input risks before execution. |
Validate descriptor provenance and constrain runtime generation before any NHI-related automation consumes it.
Related resources from NHI Mgmt Group
- What breaks when a Linux kernel file descriptor theft bug is present?
- What breaks when npm packages execute code through binding.gyp instead of package.json scripts?
- What breaks when an API parser accepts untrusted XML inside a JSON workflow?
- How should security teams decide whether to use TOON or JSON for AI agent input?
