stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/contracts/verification-policy.md
master cc69d332e3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Add unit tests for RabbitMq and Udp transport servers and clients 
- Implemented comprehensive unit tests for RabbitMqTransportServer, covering constructor, disposal, connection management, event handlers, and exception handling.
- Added configuration tests for RabbitMqTransportServer to validate SSL, durable queues, auto-recovery, and custom virtual host options.
- Created unit tests for UdpFrameProtocol, including frame parsing and serialization, header size validation, and round-trip data preservation.
- Developed tests for UdpTransportClient, focusing on connection handling, event subscriptions, and exception scenarios.
- Established tests for UdpTransportServer, ensuring proper start/stop behavior, connection state management, and event handling.
- Included tests for UdpTransportOptions to verify default values and modification capabilities.
- Enhanced service registration tests for Udp transport services in the dependency injection container.
2025-12-05 19:01:12 +02:00

7.3 KiB
Raw Permalink Blame History

Verification Policy Contract

Contract ID: CONTRACT-VERIFICATION-POLICY-006 Version: 1.0 Status: Published Last Updated: 2025-12-05

Overview

This contract defines the VerificationPolicy schema used to configure attestation verification requirements. It specifies which predicate types are allowed, signer requirements, and tenant-scoped verification rules.

Implementation References

  • Predicate Types: src/Signer/StellaOps.Signer/StellaOps.Signer.Core/PredicateTypes.cs
  • Attestor Core: src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Verification/
  • Schema: src/Attestor/StellaOps.Attestor.Types/schemas/verification-policy.v1.schema.json

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stellaops.io/schemas/verification-policy.v1.json",
  "title": "VerificationPolicy",
  "description": "Attestation verification policy configuration",
  "type": "object",
  "required": ["policyId", "version", "predicateTypes", "signerRequirements"],
  "properties": {
    "policyId": {
      "type": "string",
      "description": "Unique policy identifier",
      "pattern": "^[a-z0-9-]+$"
    },
    "version": {
      "type": "string",
      "description": "Policy version (SemVer)",
      "pattern": "^\\d+\\.\\d+\\.\\d+$"
    },
    "description": {
      "type": "string",
      "description": "Human-readable policy description"
    },
    "tenantScope": {
      "type": "string",
      "description": "Tenant ID this policy applies to, or '*' for all tenants"
    },
    "predicateTypes": {
      "type": "array",
      "description": "Allowed attestation predicate types",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "signerRequirements": {
      "$ref": "#/$defs/SignerRequirements"
    },
    "validityWindow": {
      "$ref": "#/$defs/ValidityWindow"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "$defs": {
    "SignerRequirements": {
      "type": "object",
      "properties": {
        "minimumSignatures": {
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "description": "Minimum number of valid signatures required"
        },
        "trustedKeyFingerprints": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^sha256:[a-f0-9]{64}$"
          },
          "description": "List of trusted signer key fingerprints"
        },
        "trustedIssuers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of trusted issuer identities"
        },
        "requireRekor": {
          "type": "boolean",
          "default": false,
          "description": "Require Rekor transparency log entry"
        },
        "algorithms": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["ES256", "ES384", "ES512", "RS256", "RS384", "RS512", "EdDSA"]
          },
          "description": "Allowed signing algorithms"
        }
      }
    },
    "ValidityWindow": {
      "type": "object",
      "properties": {
        "notBefore": {
          "type": "string",
          "format": "date-time",
          "description": "Policy not valid before this time"
        },
        "notAfter": {
          "type": "string",
          "format": "date-time",
          "description": "Policy not valid after this time"
        },
        "maxAttestationAge": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum age of attestation in seconds"
        }
      }
    }
  }
}

Example Policy

{
  "policyId": "default-verification-policy",
  "version": "1.0.0",
  "description": "Default verification policy for StellaOps attestations",
  "tenantScope": "*",
  "predicateTypes": [
    "stella.ops/sbom@v1",
    "stella.ops/vex@v1",
    "stella.ops/vexDecision@v1",
    "stella.ops/policy@v1",
    "stella.ops/promotion@v1",
    "stella.ops/evidence@v1",
    "stella.ops/graph@v1",
    "stella.ops/replay@v1",
    "https://slsa.dev/provenance/v1",
    "https://cyclonedx.org/bom",
    "https://spdx.dev/Document",
    "https://openvex.dev/ns"
  ],
  "signerRequirements": {
    "minimumSignatures": 1,
    "trustedKeyFingerprints": [
      "sha256:abc123...",
      "sha256:def456..."
    ],
    "requireRekor": false,
    "algorithms": ["ES256", "RS256", "EdDSA"]
  },
  "validityWindow": {
    "maxAttestationAge": 86400
  }
}

Predicate Types

StellaOps Types

Type URI Description
stella.ops/promotion@v1 Promotion attestation
stella.ops/sbom@v1 SBOM attestation
stella.ops/vex@v1 VEX attestation
stella.ops/vexDecision@v1 VEX decision with reachability
stella.ops/replay@v1 Replay manifest attestation
stella.ops/policy@v1 Policy evaluation result
stella.ops/evidence@v1 Evidence chain
stella.ops/graph@v1 Graph/reachability attestation

Third-Party Types

Type URI Description
https://slsa.dev/provenance/v0.2 SLSA Provenance v0.2
https://slsa.dev/provenance/v1 SLSA Provenance v1.0
https://cyclonedx.org/bom CycloneDX SBOM
https://spdx.dev/Document SPDX SBOM
https://openvex.dev/ns OpenVEX

Verification Flow

1. Parse DSSE envelope
2. Extract predicate type from in-toto statement
3. Check predicate type against policy.predicateTypes
4. Verify signature(s) meet policy.signerRequirements
   a. Check algorithm is allowed
   b. Verify minimum signature count
   c. Check key fingerprints against trusted list
5. If requireRekor, verify Rekor log entry
6. Check attestation timestamp against validityWindow
7. Return verification result

API Endpoints

Create Policy

POST /api/v1/attestor/policies
Content-Type: application/json

{
  "policyId": "custom-policy",
  "version": "1.0.0",
  ...
}

Response: 201 Created

Get Policy

GET /api/v1/attestor/policies/{policyId}

Response: 200 OK
{ ... }

Verify Attestation

POST /api/v1/attestor/verify
Content-Type: application/json

{
  "envelope": "base64-encoded DSSE envelope",
  "policyId": "default-verification-policy"
}

Response: 200 OK
{
  "valid": true,
  "predicateType": "stella.ops/sbom@v1",
  "signatureCount": 1,
  "signers": [
    {
      "keyFingerprint": "sha256:...",
      "algorithm": "ES256",
      "verified": true
    }
  ],
  "rekorEntry": null
}

Verification Result

{
  "valid": true,
  "predicateType": "stella.ops/sbom@v1",
  "signatureCount": 1,
  "signers": [
    {
      "keyFingerprint": "sha256:abc123...",
      "issuer": "https://stellaops.io/signer",
      "algorithm": "ES256",
      "verified": true
    }
  ],
  "rekorEntry": {
    "uuid": "24296fb24b8ad77a...",
    "logIndex": 12345,
    "integratedTime": "2025-12-05T10:00:00Z"
  },
  "attestationTimestamp": "2025-12-05T09:59:59Z",
  "policyId": "default-verification-policy",
  "policyVersion": "1.0.0"
}

Unblocks

This contract unblocks the following tasks:

  • POLICY-ATTEST-73-001
  • POLICY-ATTEST-73-002
  • POLICY-ATTEST-74-001
  • POLICY-ATTEST-74-002

Related Contracts