Compliance & Governance

Enforce organizational standards for API mocks with compliance policies. Scan Sandboxes for violations, generate audit reports, and ensure mocks meet security, quality, and consistency requirements.

Why Use Compliance Policies

• Enforce standards - Require specific headers, authentication, or data formats
• Security checks - Detect insecure configurations (hardcoded secrets, CORS misconfiguration)
• Audit readiness - Track policy compliance for SOC2, ISO27001, or internal audits
• Consistency - Ensure all teams follow the same mocking practices
• Risk reduction - Catch issues before mocks reach production-facing environments

How It Works

1. Define policies specifying required or forbidden configurations
2. Attach policies to Sandboxes, environments, or your entire organization
3. SureStage scans resources automatically and reports violations
4. Violations can trigger alerts, block deployments, or generate compliance reports

Creating Policies

API Request

curl -X POST https://api.surestage.com/v1/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Baseline",
    "description": "All mocks must meet minimum security standards",
    "scope": "company",
    "rules": [
      {
        "id": "require-auth-header",
        "type": "required_header",
        "header": "Authorization",
        "severity": "error",
        "message": "All routes must require Authorization header"
      },
      {
        "id": "no-hardcoded-secrets",
        "type": "pattern_match",
        "pattern": "(api[_-]?key|password|secret|token)\\s*[:=]\\s*[\"'\\'][^\"'']+[\"'\\']",
        "severity": "critical",
        "message": "Hardcoded secrets detected in route response"
      }
    ],
    "enforcement": "warn"
  }'

Response 201 Created

{
  "id": "policy_xyz789",
  "name": "Security Baseline",
  "description": "All mocks must meet minimum security standards",
  "scope": "company",
  "rules": [ /* ... */ ],
  "enforcement": "warn",
  "createdAt": "2026-03-21T10:00:00Z"
}

Parameters

Field	Type	Required	Description
name	string	Yes	Policy name
description	string	No	Policy description
scope	string	Yes	company, sandbox, or environment
rules	array	Yes	Array of policy rules (see below)
enforcement	string	No	warn, block, or audit (default: warn)

Policy Rule Types

Required Header

Enforce that routes include specific headers:

{
  "id": "require-content-type",
  "type": "required_header",
  "header": "Content-Type",
  "value": "application/json",
  "severity": "error",
  "message": "All routes must return JSON"
}

Field	Description
header	Header name
value	Expected header value (optional — omit to require presence only)
severity	info, warning, error, critical

Forbidden Header

Block routes with specific headers:

{
  "id": "no-server-header",
  "type": "forbidden_header",
  "header": "Server",
  "severity": "warning",
  "message": "Do not expose server implementation details"
}

Pattern Match

Scan route responses for patterns (regex):

{
  "id": "no-pii-in-logs",
  "type": "pattern_match",
  "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b",
  "severity": "critical",
  "message": "Social Security Numbers detected in response"
}

Useful for detecting:

• Hardcoded secrets
• PII (SSN, credit cards)
• Insecure URLs (http:// instead of https://)

Required Variable

Enforce use of environment variables instead of hardcoded values:

{
  "id": "use-env-vars",
  "type": "required_variable",
  "variablePattern": "API_KEY|SECRET|TOKEN",
  "severity": "error",
  "message": "Use environment variables for sensitive values"
}

Response Status

Restrict or require specific status codes:

{
  "id": "no-500-errors",
  "type": "forbidden_status",
  "statusCode": 500,
  "severity": "warning",
  "message": "Do not mock 500 errors — use specific error codes"
}

Contract Requirement

Require routes to have an attached contract:

{
  "id": "require-contract",
  "type": "contract_required",
  "severity": "error",
  "message": "All routes must have a contract"
}

Enforcement Modes

Warn Mode

Violations are logged but do not block operations:

{
  "enforcement": "warn"
}

Users see warnings when creating or modifying routes:

{
  "routeId": "route_123",
  "created": true,
  "policyViolations": [
    {
      "policyId": "policy_xyz789",
      "ruleId": "require-auth-header",
      "severity": "error",
      "message": "All routes must require Authorization header"
    }
  ]
}

Block Mode

Violations prevent route creation:

{
  "enforcement": "block"
}

{
  "error": "POLICY_VIOLATION",
  "message": "Route violates policy: Security Baseline",
  "violations": [
    {
      "ruleId": "require-auth-header",
      "severity": "error",
      "message": "All routes must require Authorization header"
    }
  ]
}

Audit Mode

Violations are logged silently without notifying users. Use for passive monitoring.

{
  "enforcement": "audit"
}

Scanning for Violations

The Policy Scanner Service runs automatically when you create or modify routes. You can also trigger manual scans.

Scan a Sandbox

curl -X POST https://api.surestage.com/v1/policies/policy_xyz789/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "sandbox",
    "targetId": "sandbox_abc123"
  }'

Response 202 Accepted

{
  "scanId": "scan_def456",
  "policyId": "policy_xyz789",
  "targetType": "sandbox",
  "targetId": "sandbox_abc123",
  "status": "in_progress",
  "startedAt": "2026-03-21T11:00:00Z"
}

Get Scan Results

curl https://api.surestage.com/v1/policies/policy_xyz789/scans/scan_def456 \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "scanId": "scan_def456",
  "policyId": "policy_xyz789",
  "status": "completed",
  "startedAt": "2026-03-21T11:00:00Z",
  "completedAt": "2026-03-21T11:00:15Z",
  "results": {
    "totalRoutes": 42,
    "violations": [
      {
        "routeId": "route_123",
        "path": "/users/:id",
        "ruleId": "require-auth-header",
        "severity": "error",
        "message": "All routes must require Authorization header"
      },
      {
        "routeId": "route_456",
        "path": "/config",
        "ruleId": "no-hardcoded-secrets",
        "severity": "critical",
        "message": "Hardcoded secrets detected in route response"
      }
    ],
    "summary": {
      "critical": 1,
      "error": 1,
      "warning": 0,
      "info": 0
    }
  }
}

Viewing Violations

List Violations

curl "https://api.surestage.com/v1/violations?sandboxId=sandbox_abc123" \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "violations": [
    {
      "id": "violation_abc123",
      "policyId": "policy_xyz789",
      "policyName": "Security Baseline",
      "ruleId": "no-hardcoded-secrets",
      "severity": "critical",
      "message": "Hardcoded secrets detected in route response",
      "resourceType": "route",
      "resourceId": "route_456",
      "detectedAt": "2026-03-21T11:00:15Z",
      "status": "open"
    }
  ]
}

Resolve Violation

Mark a violation as resolved after fixing the issue:

curl -X PATCH https://api.surestage.com/v1/violations/violation_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution": "Replaced hardcoded secret with environment variable"
  }'

Ignore Violation

Mark a violation as acknowledged but not requiring action:

curl -X PATCH https://api.surestage.com/v1/violations/violation_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ignored",
    "reason": "Test route for demo purposes only"
  }'

Compliance Reports

Generate reports for audit purposes showing policy compliance over time.

Generate Report

curl -X POST https://api.surestage.com/v1/compliance-reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2026 Compliance Report",
    "scope": "company",
    "startDate": "2026-01-01T00:00:00Z",
    "endDate": "2026-03-31T23:59:59Z",
    "includePolicies": ["policy_xyz789", "policy_security_001"]
  }'

Response 202 Accepted

{
  "reportId": "report_ghi789",
  "name": "Q1 2026 Compliance Report",
  "status": "generating",
  "createdAt": "2026-03-21T12:00:00Z"
}

Download Report

curl https://api.surestage.com/v1/compliance-reports/report_ghi789/download \
  -H "Authorization: Bearer $TOKEN" \
  -o compliance-report.pdf

Reports include:

• Policy compliance summary
• Violation trends over time
• Top violating resources
• Severity breakdown
• Remediation recommendations

Report Formats

Format	Use Case
PDF	Executive summaries, auditor distribution
CSV	Data analysis, dashboards
JSON	Programmatic consumption, integrations

Managing Policies

List Policies

curl https://api.surestage.com/v1/policies?scope=company \
  -H "Authorization: Bearer $TOKEN"

Update Policy

curl -X PATCH https://api.surestage.com/v1/policies/policy_xyz789 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enforcement": "block"
  }'

Changing enforcement mode affects all future operations immediately.

Delete Policy

curl -X DELETE https://api.surestage.com/v1/policies/policy_xyz789 \
  -H "Authorization: Bearer $TOKEN"

Deleting a policy does not resolve existing violations. They remain in the violations log for historical tracking.

Example Policies

Security Baseline

{
  "name": "Security Baseline",
  "rules": [
    {
      "type": "required_header",
      "header": "Authorization",
      "severity": "error"
    },
    {
      "type": "pattern_match",
      "pattern": "(api[_-]?key|password|secret)\\s*[:=]",
      "severity": "critical"
    },
    {
      "type": "forbidden_header",
      "header": "X-Powered-By",
      "severity": "warning"
    }
  ]
}

API Standards

{
  "name": "API Standards",
  "rules": [
    {
      "type": "required_header",
      "header": "Content-Type",
      "value": "application/json",
      "severity": "error"
    },
    {
      "type": "contract_required",
      "severity": "error"
    },
    {
      "type": "forbidden_status",
      "statusCode": 500,
      "severity": "warning"
    }
  ]
}

Data Privacy

{
  "name": "Data Privacy",
  "rules": [
    {
      "type": "pattern_match",
      "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b",
      "severity": "critical",
      "message": "SSN detected"
    },
    {
      "type": "pattern_match",
      "pattern": "\\b\\d{16}\\b",
      "severity": "critical",
      "message": "Credit card number detected"
    }
  ]
}

Security

• All policy operations are protected by JwtAuthGuard and TenantGuard
• Company-scoped policies apply to all Sandboxes in the organization
• Policy scans and violations are logged for audit trails
• Only users with admin role can create or modify policies

Common Issues

Problem: Policy not triggering violations

Solution: Verify the policy scope matches the resource being checked. Company policies apply everywhere; Sandbox policies only apply to that specific Sandbox.

Problem: Too many false positives

Solution: Refine your regex patterns or adjust severity levels. Use audit mode initially to tune policies before enforcing them.

Problem: Cannot resolve violation

Solution: Fix the underlying issue in the route or resource, then mark the violation as resolved. Violations persist until explicitly resolved or ignored.

Related

• API Contract Testing - Enforce API contracts
• Environment Variables - Use variables to avoid hardcoded values
• Audit Logs - View all policy enforcement events