SIEP: Agent-produced code provenance fields

[tomjwxf]

Edit from @eddie-knight

This was originally opened as pre-emptive discussion. As the conversation has coalesced into a proposal, I have adjusted the name accordingly. Please reference the comments below for the official SIEP details.

Hi maintainers,

Opening this as a scope-check question rather than a formal [SIEP] since I am a non-maintainer and want to gauge fit before asking for sponsorship.

Context

AI agents are increasingly producing code and commits in OSS repositories, typically through Claude Code, Cursor, or similar tool-calling hosts. A downstream consumer of a package looking at security-insights.yml can learn whether the project has a vulnerability reporting process, a signing policy, etc. They cannot currently learn whether the code was produced wholly or partly by an AI agent, and if so, what governance was in place.

This is a self-report gap that feels like a natural fit for Security Insights: machine-readable, self-declared, relative to the commit or release, and lets end-users and tooling make informed decisions. I do not think it fits SBOM (which is about dependencies, not production method) or SLSA directly (which is about build provenance, not self-declaration).

Sketch of what fields might look like

Not a formal proposal, just a starting point to discuss whether the shape is right:

project:
  agent-usage:
    status: partial   # none | partial | primary
    description: |
      AI agents are used for test generation and documentation updates
      under human review. Production code is primarily human-authored.
    governance:
      policy-source: https://github.com/example/policy.cedar
      policy-digest: sha256:8f3a...
      receipts-verifier: "npx @veritasacta/verify"
      receipts-format: draft-farley-acta-signed-receipts
    agents:
      - name: claude-code
        runtime-uri: https://claude.com/claude-code
      - name: cursor
        runtime-uri: https://cursor.sh

The fields are all self-declared (same trust model as the rest of SI), machine-parseable, and let downstream tooling filter or flag based on declared agent usage.

Questions for the maintainers

1. Scope: is "production method" (human vs agent) something Security Insights wants to model, or is that out of scope on purpose?
2. Precedent: are there existing fields I should map onto instead of proposing new ones? The closest I see are the repository.code-of-conduct and distribution-points fields, but neither is a tight fit.
3. Sponsorship: if the idea has scope fit, is there a maintainer interested in sponsoring a formal SIEP? Happy to do the drafting and schema work.
4. Timing: does this intersect with current work on the spec (e.g., is 2.2 or 3.0 accepting new top-level fields)?

Why this matters to the broader ecosystem

This intersects with several concurrent efforts I have been tracking:

• draft-sharif-mcps-secure-mcp: agent identity via per-message ECDSA signing
• draft-farley-acta-signed-receipts: per-tool-call decision receipts (I am the author)
• arewm/refs.arewm.com agent-commit v0.1: SLSA provenance build type for agent-produced commits
• slsa-framework/slsa#1594: SLSA-for-agents discussion
• in-toto/attestation#549: decision-receipts as an attestation predicate type

The downstream piece that is missing is the self-declaration layer where a project announces "yes, agents produced some of this, here is how to verify." Security Insights already plays that role for the rest of the security posture, which is why I am asking here first.

Acknowledgment

Happy to defer to maintainer judgment on whether this fits the spec charter. If the answer is "out of scope, try OSPS Baseline or a sibling project instead," that is useful information too.

Thanks for the work on the spec.

Tom Farley
(independent contributor; author of draft-farley-acta-signed-receipts)

[aeoess]

+1 on this fitting Security Insights rather than SBOM or SLSA. The self-declaration shape matches SI's existing trust model, and production-method (human vs agent) is a first-order concern for downstream consumers that neither SBOM nor SLSA addresses.

Two observations from the agent-governance side that may sharpen the sketch before a formal SIEP:

On receipts-format as a single string. The draft sketch pins receipts-format: draft-farley-acta-signed-receipts, which works if the ecosystem converges on a single format. In practice there are already multiple shapes in production (Acta v1 flat, Acta v2 envelope, APS enforcement records, and several bilateral-signed variants from other ecosystems). Two options keep the field forward-compatible:

receipts:
  formats:
    - name: draft-farley-acta-signed-receipts
      version: "01"
      verifier: "npx @veritasacta/verify"
    - name: aps-enforcement-record
      version: "1.0"
      verifier: "npx agent-passport-system verify"

Or the more conservative variant — receipts-format takes a URI pointing at a machine-readable spec identifier, and the verifier field takes a list. Either way, the SI-consuming tool can dispatch on format without a schema breaking change when a second format lands.

On governance.policy-source being a URL. Policies change. Pinning to a URL gives you the current state but doesn't let a downstream consumer verify that a specific commit or release was produced under a specific policy version. Adding policy-digest alongside policy-source (which the sketch already has) answers "was the authority under this policy at this moment" — but worth making explicit that policy-digest is the required field for downstream verification, and policy-source is a convenience pointer that can drift.

Precedent beyond the fields you flagged. Closest existing SI field is probably vulnerability-reporting.bug-bounty-available — also self-declared, machine-parseable, opinion-free (presence/absence is the signal, not a value judgment). agent-usage.status: none | partial | primary matches that shape well. Worth leaning into that parallel in the SIEP framing to defuse "is this a value judgment on agents" objections — it's a data field, same as any other.

On scope. Strong agree this sits in SI, not SBOM/SLSA. A related question worth naming in the SIEP: does the field apply at the project level or per-release? Both are useful for different consumer queries ("has this project ever used agents" vs "was this specific release produced with agent involvement"). The sketch implies project-level; per-release is probably what consumers actually want for security posture decisions.

Happy to co-draft the SIEP if a sponsor emerges. APS ships governance_attestation envelopes that slot into the receipts field as a second format, and the cross-format verifier pattern is testable today against both Acta and APS receipt samples.

[tomjwxf]

@aeoess all three improvements land and each is better than what I had. Let me accept them specifically so we are aligned for a joint SIEP if a sponsor emerges.

Receipts-format as array. Yes, and your formats[] shape is cleaner than what I drafted. A single format field assumes ecosystem convergence that has not happened (and probably should not happen — multiple formats means multiple verifiers, which means no single vendor controls verification). Forward-compatible at drafting time is the right default. I will use your shape.

Policy-digest as required, policy-source as optional pointer. Agreed. The digest is what a downstream consumer verifies against; the URL is user-experience convenience. Making policy-digest required forces the self-declaration to be verifiable rather than aspirational. policy-source stays optional, documented as "may drift; see policy-digest for verifiability."

Per-release granularity, not project-level. You are right that per-release is what security-posture consumers actually need. "Was this specific release produced with agent involvement" is a concrete question; "does this project sometimes use agents" is vague. The SI spec already has release-adjacent fields; the agent-usage field should live at the same scope.

Precedent framing around bug-bounty-available. Strong yes. Modeling agent-usage as opinion-free self-declared data (status values, not scores) defuses the "is this a value judgment" objection cleanly. I will lead the SIEP framing with exactly that analogy.

Revised sketch incorporating all four points:

project:
  agent-usage:
    status: partial              # none | partial | primary (self-declared, opinion-free)
    # Per-release: the fields below MAY vary between releases
    description: |
      AI agents are used for test generation and documentation updates
      under human review. Production code is primarily human-authored.
    governance:
      policy-digest: sha256:8f3a...    # REQUIRED for verifiability
      policy-source: https://github.com/example/policy.cedar  # optional pointer, may drift
      receipts:
        formats:
          - name: draft-farley-acta-signed-receipts
            version: "01"
            verifier: "npx @veritasacta/verify"
          - name: aps-enforcement-record
            version: "1.0"
            verifier: "npx agent-passport-system verify"
    agents:
      - name: claude-code
        runtime-uri: https://claude.com/claude-code
      - name: cursor
        runtime-uri: https://cursor.sh

Accepting the co-drafting offer. Yes please. With your shape corrections this SIEP reads as a joint contribution rather than my solo draft. If a maintainer sponsors the scope fit, I would like to open the formal SIEP with us as co-authors. Your APS governance_attestation envelope being a second format (not a replacement) proves the array-valued shape is the right call.

Maintainer ping. @eddie-knight @scovetta who have sponsored SIEPs before — if this direction is in scope for v2.2 or v3.0, aeoess and I would like to formally submit. Happy to do all the schema and spec drafting if the scope answer is yes. If it is not the right repo and OSPS Baseline or a sibling is a better fit, please redirect and we will take it there.

Thanks @aeoess for the tight read. The SIEP is materially better with all four of these in it.

[jmeridth]

This is interesting. I'm reading through it.

Note: the em dashes are giving it away all of this is AI driven. Doesn't mean the content is wrong but it is verbose and will take time to consume and respond.

Cheers.

[tomjwxf]

Thank you @jmeridth I appreciate you taking the time to engage with the substance, even if over-polished by Claude. I do increasingly use AI for everything, frighteningly.

My three actual questions:

1. Does Security Insights scope include self-declared agent-usage (human vs AI production method) as a project or per-release field? The sketch is just a starting point for the shape.
2. If scope fit is yes, is anyone on the team willing to sponsor a formal SIEP? I will do the drafting and schema work.
3. If scope fit is no, is there a sibling project you would redirect to? OSPS Baseline, scorecard, somewhere else?

Everything in the longer threads above is admittedly cart before the horse.

[eddie-knight]

Thanks for raising this as a standalone brainstorming issue. I think there's a lot to refine, but it's a great suggestion overall.

To answer some of the questions above...

• Absolutely, this topic is well enough in scope to consider
• I think that project-level statements are probably sufficient for most use cases, though there is a legitimate edge case where AI usage may be need to be tailored on a per repository basis

Some other thoughts...

1. I suspect some of the intent behind this proposal could be answered by the existing field repository.accepts-automated-change-request (boolean, "Indicates whether the repository accepts automated or machine-generated change requests")
2. I am concerned about the present shape using Cedar as the policy artifact, since that feels more focused on policy-implementation instead of actually pointing to the presence of a policy
3. There are other related questions that some big projects are sorting through related to AI, such as mandatory identification of AI assistance, or restricting whether you can name your AI tool in commits. This could be included in a new project.documentation or repo.documentation field related to AI acceptable use policy

[tomjwxf]

Thanks @eddie-knight Eddie, initial thoughts:

1. Project-level default with per-release override probably splits the difference. Most projects set it once; ones that change practice between releases need somewhere to declare that.
2. Ack on repository.accepts-automated-change-request. That's "do you accept PRs from agents?" vs this proposal's "were agents used to produce this code?" Sibling fields, worth cross-linking.
3. Agreed on dropping the Cedar assumption. Better: policy-digest + optional policy-source + optional policy-format enum (cedar, rego, opa, custom).

AI acceptable-use policy feels like a separate proposal. Different shape (narrative, human-readable) and different consumer. Happy to keep this SIEP focused on production-method, open a sibling issue for AUP. Can start the SIEP draft this week? Let me know.

[aeoess]

Adding a specifics-oriented +1 on eddie-knight's scope read, since APS is one of the governance frameworks this would name.

A project-level declaration is the right granularity. Per-release tagging seems like where it wants to go eventually (projects migrate in and out of agent-assisted production over time, and a stale declaration is worse than none), but shipping v1 as project-level keeps the first merge tractable and lets adoption data tell us where per-release belongs.

On the one-field-vs-multi-field question: a compact discriminator with an optional details URI reads cleaner than trying to capture governance posture in the YAML directly. Something like:

agent-assisted-production:
  used: true
  governance-declaration: https://example.com/.well-known/agent-governance

The declaration URI points at whatever framework the project chose (APS, AiEGIS, SINT, any self-published governance statement). That keeps Security Insights out of the business of ranking frameworks while giving downstream consumers a canonical place to look. The used: false path covers the "definitely no agent" case; omission covers "not declared." Three distinct states, one field plus one URI.

From the APS side, the surface that would naturally slot in as a governance-declaration target is already shipped: a signed attestation served at /.well-known/aps.txt declaring issuer, trust-profile endpoint, JWKS, and governance attestation algorithm. A project using APS could point its Security Insights declaration at its own aps.txt and the dereference chain lands on cryptographically-verifiable state. A project using a different framework points at that framework's well-known path. Security Insights stays neutral on which framework is used, just that one is declared.

On sponsorship: @eddie-knight's read that this fits in scope is the signal that a SIEP is worth drafting. Happy to contribute API-surface details or a worked example declaration for APS-governed projects when the SIEP lands.

Tymofii

[tomjwxf]

thanks @aeoess shape is materially cleaner. Three birds, one stone:

1. eddie-knight's point about SI staying neutral on policy-language choice
2. the receipts-format multiplicity we discussed earlier in this thread
3. forward-compatibility for any governance framework
   A governance-declaration URI keeps SI out of the framework-ranking business.

Proposed v0.1:

agent-assisted-production:
  used: true
  governance-declaration: https://example.com/.well-known/agent-governance
Three distinct states: used: false (declared no agent), used: true + URI
(declared with governance pointer), field omitted (not declared).

Project-level default for v0.1 per your and eddie-knight's reads. v0.2 can add
per-release override if adoption signals demand.

APS's /.well-known/aps.txt spec is a natural target for APS-governed projects.
Acta can define an equivalent for receipt-signing projects if useful. SI stays
neutral on which spec any project chooses.

Ready to draft the SIEP. @eddie-knight if scope still holds with this
simplified shape, @aeoess and I can open the formal PR this week.

[aeoess]

@tomjwxf — circling back on the SIEP draft. Last week you flagged the co-PR shape as ready (agent-assisted-production: { used, governance-declaration }, project-level for v0.1, eddie-knight's neutrality read confirmed). Happy to co-author when you're ready to open.

If scope has shifted in the meantime (or if you'd rather hold pending other SI conversations), no pressure on the timeline. Just checking the ball isn't sitting in either of our courts by accident.

@eddie-knight, flagging in case you have a sponsor-level read on whether the simplified shape still fits the SI roadmap, or whether anything in the receipts-format multiplicity discussion has shifted since.

[tomjwxf]

Thanks, this is on me. Scope has not shifted.

I opened a focused v0.1 PR here: #175

The proposed Security Insights surface is intentionally small and vendor-neutral:

project:
  agent-assisted-production:
    used: true
    governance-declaration: https://example.com/.well-known/agent-governance

The PR keeps framework-specific receipt formats, policy engines, and attestations out of the SI schema. Those details live behind the optional declaration URI, so projects can point to a human-readable policy, in-toto attestations, Acta receipts, SLSA provenance, or another governance declaration without locking Security Insights to any one framework.

[eddie-knight]

SIEP-171

Provide a record of the project's policy regarding agentic authorship of code. This is especially relevant for spec-driven projects where AI involvement is more than simple assistance.

Detailed Design

Two fields are proposed, one for whether agentic assistance is used, and the other to document the relevant governance policy. Policies should be.

1. project.documentation.ai-contribution-policy
2. repo.agentic-assissted-production

Impact

Captures policies for the entire project, while agentic involvement may vary from one repository to the next.

Compatibility

No changes to existing fields, no duplication with existing fields. Minor overlap with repo.accepts-automated-change-request.

Alternatives

See previous discussion in this thread. Especially:

1. project.agent-assisted-production.used
2. project.agent-assisted-production.governance-declaration

Open Questions

This adjustment is pending confirmation from the original author @tomjwxf

Sponsoring Maintainer Assigned

@eddie-knight

[tomjwxf]

Thanks @eddie-knight confirming from my side.

I support SIEP-171 and the sponsor direction. One correction: I think the machine-readable field should stay aligned with PR #175 unless you want me to rework that PR. The current PR uses:

project.agent-assisted-production.used
project.agent-assisted-production.governance-declaration

That keeps Security Insights schema-neutral and lets the declaration URI point to a human policy, Acta receipts, APS, in-toto attestations, SLSA provenance, or a project-specific statement.

If you prefer the split in this comment, I can revise PR #175 to add project.documentation.ai-contribution-policy as the human-readable policy pointer and use repository.agent-assisted-production as an optional repo-level override.

Also noting one typo in the sketch above: repo.agentic-assessted-production should probably be repository.agent-assisted-production.

My preference for v0.1 remains the smaller PR #175 shape, with documentation policy as a follow-up if needed.

Best,
Tom