git.stella-ops.org/docs/contracts/policy-studio.md

Policy Studio API Contract

Contract ID: CONTRACT-POLICY-STUDIO-007 Version: 1.0 Status: Published Last Updated: 2025-12-05

Overview

This contract defines the Policy Studio API used for creating, editing, and managing security policies. Policy Studio extends the Policy Engine REST API with DSL compilation and draft management capabilities.

Implementation References

• Policy Engine: src/Policy/StellaOps.Policy.Engine/
• Policy API: src/Api/StellaOps.Api.OpenApi/policy/openapi.yaml
• Documentation: docs/api/policy.md

Policy Lifecycle

Draft → Submitted → Approved → Active → Archived

State	Description
draft	Policy is being edited, not enforced
submitted	Policy submitted for review
approved	Policy approved, ready to activate
active	Policy is currently enforced
archived	Policy is no longer active

API Endpoints

Draft Management

Create Draft

POST /api/v1/policy/drafts
Content-Type: application/json
Authorization: Bearer <token>

{
  "tenant_id": "default",
  "name": "security-policy-v2",
  "description": "Enhanced security policy with KEV checks",
  "source_format": "stelladsl",
  "source": "package policy\n\ndefault allow := false\n\nallow if {\n  input.severity != \"critical\"\n}"
}

Response: 201 Created
{
  "draft_id": "draft-001",
  "name": "security-policy-v2",
  "state": "draft",
  "created_at": "2025-12-05T10:00:00Z",
  "created_by": "user@example.com"
}

Get Draft

GET /api/v1/policy/drafts/{draft_id}

Response: 200 OK
{
  "draft_id": "draft-001",
  "name": "security-policy-v2",
  "description": "Enhanced security policy with KEV checks",
  "state": "draft",
  "source_format": "stelladsl",
  "source": "...",
  "compiled_rego": "...",
  "validation_errors": [],
  "created_at": "2025-12-05T10:00:00Z",
  "updated_at": "2025-12-05T10:00:00Z"
}

Update Draft

PUT /api/v1/policy/drafts/{draft_id}
Content-Type: application/json

{
  "source": "updated policy source..."
}

Response: 200 OK

Delete Draft

DELETE /api/v1/policy/drafts/{draft_id}

Response: 204 No Content

DSL Compilation

Compile DSL to Rego

POST /api/v1/policy/dsl/compile
Content-Type: application/json

{
  "source": "package policy\n\ndefault allow := false\n\nallow if { input.severity != \"critical\" }",
  "format": "stelladsl"
}

Response: 200 OK
{
  "rego": "package policy\n\ndefault allow := false\n\nallow = true {\n  input.severity != \"critical\"\n}",
  "errors": [],
  "warnings": [
    {
      "line": 5,
      "column": 1,
      "message": "Consider adding documentation comment"
    }
  ]
}

Validate Policy

POST /api/v1/policy/dsl/validate
Content-Type: application/json

{
  "source": "...",
  "format": "stelladsl"
}

Response: 200 OK
{
  "valid": true,
  "errors": [],
  "warnings": []
}

Submission & Approval

Submit Draft for Review

POST /api/v1/policy/drafts/{draft_id}/submit
Content-Type: application/json

{
  "comment": "Ready for review"
}

Response: 200 OK
{
  "draft_id": "draft-001",
  "state": "submitted",
  "submitted_at": "2025-12-05T10:00:00Z",
  "submitted_by": "user@example.com"
}

Approve Policy

POST /api/v1/policy/drafts/{draft_id}/approve
Authorization: Bearer <token with policy:approve scope>

{
  "comment": "Approved after review"
}

Response: 200 OK
{
  "draft_id": "draft-001",
  "state": "approved",
  "approved_at": "2025-12-05T10:00:00Z",
  "approved_by": "admin@example.com"
}

Activate Policy

POST /api/v1/policy/drafts/{draft_id}/activate
Authorization: Bearer <token with policy:activate scope>

Response: 200 OK
{
  "policy_id": "policy-001",
  "version": "1.0.0",
  "state": "active",
  "activated_at": "2025-12-05T10:00:00Z"
}

Policy Versions

List Policy Versions

GET /api/v1/policy/{policy_id}/versions

Response: 200 OK
{
  "versions": [
    {
      "version": "1.0.0",
      "state": "active",
      "activated_at": "2025-12-05T10:00:00Z"
    },
    {
      "version": "0.9.0",
      "state": "archived",
      "archived_at": "2025-12-05T09:00:00Z"
    }
  ]
}

Get Specific Version

GET /api/v1/policy/{policy_id}/versions/{version}

Response: 200 OK
{
  "policy_id": "policy-001",
  "version": "1.0.0",
  "rego": "...",
  "hash": "sha256:...",
  "state": "active"
}

Policy Evaluation

Evaluate Policy

POST /api/v1/policy/{policy_id}/evaluate
Content-Type: application/json

{
  "input": {
    "finding_id": "finding-001",
    "severity": "high",
    "cvss": 7.5,
    "kev": true
  }
}

Response: 200 OK
{
  "result": {
    "allow": false,
    "deny": true,
    "reasons": ["KEV vulnerability detected"]
  },
  "policy_version": "1.0.0",
  "policy_hash": "sha256:...",
  "evaluated_at": "2025-12-05T10:00:00Z"
}

DSL Format

StellaOps DSL (stelladsl)

package policy

import future.keywords.if
import future.keywords.in

# Default deny
default allow := false
default deny := false

# Allow low severity findings
allow if {
    input.severity in ["low", "informational"]
}

# Deny KEV vulnerabilities
deny if {
    input.kev == true
}

# Deny critical CVSS
deny if {
    input.cvss >= 9.0
}

Error Codes

Code	Message
ERR_POL_001	Invalid policy syntax
ERR_POL_002	Compilation failed
ERR_POL_003	Validation failed
ERR_POL_004	Policy not found
ERR_POL_005	Invalid state transition
ERR_POL_006	Insufficient permissions

Authority Scopes

Scope	Description
policy:read	Read policies and drafts
policy:write	Create and edit drafts
policy:submit	Submit drafts for review
policy:approve	Approve submitted policies
policy:activate	Activate approved policies
policy:archive	Archive active policies

Unblocks

This contract unblocks the following tasks:

• CONCELIER-RISK-68-001
• POLICY-RISK-68-001
• POLICY-RISK-68-002

Related Contracts

• Risk Scoring Contract - Policy affects scoring
• Authority Effective Write Contract - Policy attachment