Examples

This guide provides practical examples for common compliance mapping scenarios using curl.

Setup

Set your API key as an environment variable:

export SECBERUS_API_KEY="your-api-key-here"

Example 1: Discover Available Frameworks

Before mapping documents, retrieve the list of available compliance frameworks:

curl -s -H "authorization: $SECBERUS_API_KEY" \
  https://compliance.secberus.ai/v1/frameworks | jq '.[] | {id, name, region}'

Sample Output:

{"id": "pci_dss_v4", "name": "PCI DSS v4.0", "region": "Global"}
{"id": "nist_csf_v2", "name": "NIST Cybersecurity Framework v2.0", "region": "US"}
{"id": "iso_27001", "name": "ISO/IEC 27001:2022", "region": "Global"}
{"id": "soc2", "name": "SOC 2 Type II", "region": "US"}

Example 2: Map a Single Policy to One Framework

Map an internal password policy to PCI DSS v4 controls:

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["pci_dss_v4"],
    "min_similarity": 0.3,
    "documents": [
      {
        "id": "password-policy-001",
        "document": "All user accounts must use passwords with a minimum length of 12 characters. Passwords must include uppercase letters, lowercase letters, numbers, and special characters. Passwords must be changed every 90 days and cannot reuse the last 12 passwords."
      }
    ]
  }'

Example 3: Map to Multiple Frameworks

Map a policy to multiple compliance frameworks simultaneously:

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["pci_dss_v4", "nist_csf_v2", "iso_27001"],
    "min_similarity": 0.4,
    "documents": [
      {
        "id": "access-control-policy",
        "document": "Access to production systems requires multi-factor authentication. All access is granted based on the principle of least privilege. Access rights are reviewed quarterly and revoked immediately upon employee termination."
      }
    ]
  }'

Example 4: Get Multiple Control Matches

Use topk to return the top 5 matching controls for each document:

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["pci_dss_v4"],
    "min_similarity": 0.25,
    "topk": 5,
    "documents": [
      {
        "id": "encryption-policy",
        "document": "All sensitive data must be encrypted at rest using AES-256. Data in transit must use TLS 1.2 or higher. Encryption keys are stored in a hardware security module and rotated annually."
      }
    ]
  }'

Example 5: Batch Process Multiple Documents

Map multiple policies in a single request:

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["soc2"],
    "min_similarity": 0.3,
    "topk": 2,
    "documents": [
      {
        "id": "incident-response",
        "document": "Security incidents must be reported within 24 hours. The incident response team will investigate, contain, and remediate all incidents. Post-incident reviews are conducted within 5 business days."
      },
      {
        "id": "change-management",
        "document": "All changes to production systems require approval from the change advisory board. Changes must be tested in a staging environment before deployment. Emergency changes require retrospective review."
      },
      {
        "id": "vendor-management",
        "document": "Third-party vendors must complete a security assessment before onboarding. Vendor security posture is reviewed annually. Vendors with access to customer data must sign a data processing agreement."
      }
    ]
  }'

Example 6: Filter by Confidence Level

Use min_confidence instead of min_similarity for easier threshold selection:

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["iso_27001"],
    "min_confidence": "Medium",
    "documents": [
      {
        "id": "backup-policy",
        "document": "Critical systems are backed up daily. Backups are stored offsite with 256-bit encryption. Backup restoration is tested quarterly. Retention period is 7 years for financial data."
      }
    ]
  }'

Confidence Levels (from highest to lowest):

High - Very strong semantic match
Medium - Good semantic match
Low - Moderate semantic match
Very Low - Weak semantic match

Example 7: Process JSON-Formatted Input

If your policy data is in JSON format:

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["pci_dss_v4"],
    "min_similarity": 0.3,
    "documents": [
      {
        "id": "policy-json-001",
        "format": "json",
        "document": "{\"policy_name\": \"Network Segmentation\", \"requirements\": [\"Production and development networks must be segmented\", \"Cardholder data environment isolated from corporate network\", \"Firewall rules reviewed semi-annually\"]}"
      }
    ]
  }'

Example 8: Categorize Documents

Add category metadata to organize your mappings:

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["nist_csf_v2"],
    "min_similarity": 0.35,
    "documents": [
      {
        "id": "logging-001",
        "category": "Operations",
        "document": "All systems must log authentication events, administrative actions, and data access. Logs are retained for 1 year and forwarded to centralized SIEM in real-time."
      },
      {
        "id": "awareness-001",
        "category": "Human Resources",
        "document": "All employees complete security awareness training during onboarding and annually thereafter. Phishing simulations are conducted quarterly."
      }
    ]
  }'

Example 9: Script for Bulk Processing

Process policies from a file:

#!/bin/bash

# policies.json contains an array of documents
# [{"id": "policy-1", "document": "..."}, {"id": "policy-2", "document": "..."}]

POLICIES=$(cat policies.json)

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"frameworks\": [\"pci_dss_v4\", \"soc2\"],
    \"min_similarity\": 0.3,
    \"topk\": 3,
    \"documents\": $POLICIES
  }" | jq '.'

Example 10: Extract Specific Fields from Response

Use jq to format output for reporting:

# Get just the control IDs and similarity scores
curl -s -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["pci_dss_v4"],
    "min_similarity": 0.3,
    "topk": 3,
    "documents": [
      {
        "id": "mfa-policy",
        "document": "Multi-factor authentication is required for all remote access and administrative access to systems."
      }
    ]
  }' | jq '.controls[] | {
    document: .document_id,
    control_id: .control.id,
    control_title: .control.title,
    similarity: .similarity,
    confidence: .confidence
  }'

Sample Output:

{
  "document": "mfa-policy",
  "control_id": "8.4.2",
  "control_title": "MFA for all access into the CDE",
  "similarity": 0.89,
  "confidence": "High"
}
{
  "document": "mfa-policy",
  "control_id": "8.4.1",
  "control_title": "MFA for administrative access",
  "similarity": 0.85,
  "confidence": "High"
}

Error Handling

Handle errors gracefully in scripts:

#!/bin/bash

response=$(curl -s -w "\n%{http_code}" -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: $SECBERUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["pci_dss_v4"],
    "documents": [{"id": "test", "document": "Test policy content"}]
  }')

http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -eq 200 ]; then
  echo "Success!"
  echo "$body" | jq '.controls'
else
  echo "Error (HTTP $http_code):"
  echo "$body" | jq '.detail'
fi

Best Practices

Keep documents concise - Limit each document to ~250 words for optimal mapping accuracy
Use meaningful IDs - Document IDs should be traceable back to your policy management system
Start with higher thresholds - Begin with min_similarity: 0.5 or min_confidence: "Medium" and adjust as needed
Batch similar policies - Group related policies in single requests for efficiency
Cache framework list - The framework list changes infrequently; cache it to reduce API calls