File Attestation

The File Attestation Plugin verifies that a given file exists and that its attestation is present and valid, then exposes this information as evidence to the Continuous Compliance Framework.

Typical use cases:

• Ensure a critical artifact (e.g. SBOM, manifest, binary) is present.
• Verify that the artifact is covered by a signed Sigstore-style attestation.
• Enforce that the signer of an attestation is on an approved list.
• Ensure a given standard-based report is compliant (SARIF, CTRF)

This plugin is intended to be run as part of an aggregate agent and will execute your policy suite for the configured file and its attestation.

---

This page is for operators who run the plugin-file-attestation plugin with the CCF Agent, and for developers who write policies for it. It documents v0.2.1 and is generated from the plugin's README at v0.2.1.

Requirements

Authentication

The plugin can fetch both the file and its attestation from different locations:

• Local filesystem (/path/to/file or file:///path/to/file)
• HTTP / HTTPS endpoints
• OCI-style endpoints (treated as HTTP(S) by this plugin)

Depending on where the file and attestation live, you may need authentication:

• Basic Auth
  • basic_auth_username
  • basic_auth_password
• Bearer Token
  • bearer_token

These credentials are automatically applied to http, https, and oci URIs.

Note: There is no GitHub-specific authentication in this plugin. Any GitHub access should be provided via standard HTTP(S) endpoints secured with the mechanisms above.

---

Configuration

This plugin is configured via the agent YAML under plugins:

plugins:
  file_attestation:
    # Required: path to the file whose existence should be checked.
    # Can be:
    #   - Relative path (treated as local filesystem)
    #   - file:///absolute/path
    #   - http(s)://... or oci://...
    file_path: "file:///etc/myapp/config.yaml"

    # Optional: path to the attestation associated with the file.
    # Same URI formats as `file_path`.
    attestation_path: "https://attest.example.com/config.yaml.att.json"

    # Optional: comma-separated list of authorized signers for the attestation.
    # Example: emails, identities, or URIs depending on your trust model.
    authorized_signers: "alice@example.com,bob@example.com"

    # Optional: credentials for HTTP/HTTPS/OCI endpoints.
    basic_auth_username: ""
    basic_auth_password: ""
    bearer_token: ""

Path rules

• file_path is required.
• file_path and attestation_path may be:
  • Relative filesystem paths (no URI scheme).
  • file:// URIs (local filesystem).
  • http://, https://, or oci:// URIs.
• Any other schemes (including git://) are rejected during validation.

Absolute filesystem paths are normalized to file:// internally. Relative filesystem paths are kept as relative paths.

Subject labeling

When the plugin emits evidence, it labels tracked files differently depending on where the file is sourced from:

• Local filesystem paths and file:// URIs are labeled with:
  • provider=file
  • type=attestation
  • source=local
  • host=<current host>
  • file=<absolute local file path>
• Remote http://, https://, and oci:// targets are labeled with:
  • provider=file
  • type=attestation
  • source=remote
  • host=<remote domain>
  • file=<remote path excluding the domain>

This allows the framework to resolve separate subject templates for:

• Local host-backed files
• Remote files and artifacts

HTTP example

Example agent configuration using an HTTP-hosted file:

plugins:
  file_attestation:
    file_path: "https://raw.githubusercontent.com/compliance-framework/plugin-local-ssh/main/README.md"
    authorized_signers: ""

---

Policies

The policy bundles that work with this plugin, at their newest releases. The controls are the ones the bundle's policies list in their metadata.

Bundle	Latest version	Controls covered	Compatible plugin lines
plugin-file-attestation-ctrf-policies	v0.2.0	none listed	latest
plugin-file-attestation-policies	v0.2.0	none listed	latest
plugin-file-attestation-sarif-policies	v0.2.0	none listed	latest

Policies are written in OPA/Rego and must live under the compliance_framework package namespace.

Example:

# deny_unsigned_file.rego
# package compliance_framework.[YOUR_RULE_PATH]
package compliance_framework.deny_unsigned_file

deny[msg] {
  input.attestation.exists == false
  msg := "critical file is missing an attestation"
}

The plugin exposes information about:

• File path and existence
• Attestation presence and verification status
• Attestation signer identity and issuer (where available)
• Configured authorized signers

You can use these fields to write policies such as:

• Deny when the file does not exist.
• Deny when the attestation is missing or invalid.
• Deny when the signer is not one of the authorized_signers.

Policy data

Any policy_data set on this plugin's block in the agent configuration is passed to every policy evaluation and is available to Rego as data.<key>:

plugins:
  file_attestation:
    # ...plugin settings as above...
    policy_data:
      allowed_issuers:
        - https://token.actions.githubusercontent.com

---