Adding Enrichment Providers

Calseta’s enrichment system is runtime-configurable. Adding a new provider requires zero code changes — you configure it via the REST API or by seeding the database. A single adapter class (DatabaseDrivenProvider) handles all providers.

Two Ways to Add Providers

Via API (Runtime)

Create a provider at runtime using the REST API:

curl -X POST http://localhost:8000/v1/enrichment-providers \
  -H "Authorization: Bearer cai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "greynoise",
    "display_name": "GreyNoise",
    "supported_indicator_types": ["ip"],
    "http_config": {
      "steps": [{
        "method": "GET",
        "url": "https://api.greynoise.io/v3/community/{{value}}",
        "headers": {
          "key": "{{auth_token}}"
        }
      }]
    },
    "auth_config": {
      "token": "your-greynoise-key"
    },
    "malice_rules": {
      "conditions": [
        { "field": "classification", "operator": "eq", "value": "malicious", "verdict": "Malicious" },
        { "field": "classification", "operator": "eq", "value": "unknown", "verdict": "Suspicious" },
        { "field": "classification", "operator": "eq", "value": "benign", "verdict": "Benign" }
      ]
    },
    "cache_ttl_by_type": {
      "ip": 3600
    }
  }'

Via Database Seed (Builtin)

For providers that ship with Calseta, add a seed entry in app/seed/enrichment_providers.py. This is how the four builtin providers (VirusTotal, AbuseIPDB, Okta, Entra) are defined.

HTTP Config Structure

The http_config defines how Calseta calls the provider’s API. It supports template variables that are resolved at runtime.

{
  "steps": [
    {
      "method": "GET",
      "url": "https://api.example.com/v1/lookup/{{value}}",
      "headers": {
        "Authorization": "Bearer {{auth_token}}",
        "Accept": "application/json"
      },
      "params": {
        "maxAgeInDays": "90"
      }
    }
  ]
}

Template Variables

Variable	Resolves To
`{{value}}`	The indicator value being enriched
`{{type}}`	The indicator type (`ip`, `domain`, etc.)
`{{auth_token}}`	The auth credential from `auth_config`

Auth Types

Type	Description
`no_auth`	No authentication required (default)
`api_key`	API key — stored in `auth_config`, resolved via `{{auth_token}}` in headers
`api_token`	API token — same resolution as `api_key`, named differently for clarity
`oauth2_client_credentials`	OAuth2 client credentials flow

How you send the credential (header name, format) is controlled by the http_config template — auth_type just tells Calseta whether credentials are needed and how to resolve them. For example, to send an API key in a custom header:

{
  "http_config": {
    "steps": [{
      "headers": { "X-Api-Key": "{{auth_token}}" }
    }]
  },
  "auth_config": { "token": "your-key-here" }
}

Auth credentials are encrypted at rest using the ENCRYPTION_KEY environment variable.

Malice Rules

Configure rules that map provider response fields to malice verdicts:

{
  "conditions": [
    {
      "field": "abuse_confidence_score",
      "operator": "gte",
      "value": 80,
      "verdict": "Malicious"
    },
    {
      "field": "abuse_confidence_score",
      "operator": "gte",
      "value": 25,
      "verdict": "Suspicious"
    }
  ],
  "default_verdict": "Benign"
}

Operators

Operator	Description
`eq`	Equals
`neq`	Not equals
`gte`	Greater than or equal
`lte`	Less than or equal
`in`	In list
`contains`	Contains substring

Conditions are evaluated in order — the first match wins.

Field Extractions

Define which fields from the raw provider response are surfaced to agents in the extracted object:

curl -X POST http://localhost:8000/v1/enrichment-field-extractions \
  -H "Authorization: Bearer cai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "greynoise",
    "indicator_type": "ip",
    "source_path": "data.classification",
    "target_key": "classification",
    "value_type": "string",
    "description": "GreyNoise classification: benign, malicious, or unknown"
  }'

Field	Description
`source_path`	Dot-notation path into the raw response (e.g., `data.results.score`)
`target_key`	Key name in the `extracted` object surfaced to agents
`value_type`	Expected type: `string`, `int`, `float`, `bool`, `list`, `dict`, `any`

Use the bulk create endpoint to add multiple extractions at once:

curl -X POST http://localhost:8000/v1/enrichment-field-extractions/bulk \
  -H "Authorization: Bearer cai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extractions": [
      { "provider_name": "greynoise", "indicator_type": "ip", "source_path": "data.classification", "target_key": "classification", "value_type": "string" },
      { "provider_name": "greynoise", "indicator_type": "ip", "source_path": "data.noise", "target_key": "is_noise", "value_type": "bool" }
    ]
  }'

You can list, update, and delete field extractions via the full CRUD API. Builtin provider extractions are system-managed — they can be toggled on/off but not deleted. When a custom provider is deleted, all its field extractions are automatically removed.

Cache Configuration

Set TTLs per indicator type:

{
  "cache_ttl_by_type": {
    "ip": 3600,
    "domain": 21600,
    "hash_sha256": 86400
  }
}

Values are in seconds. If not specified for a type, the system default applies.

Testing Your Provider

After adding a provider, test with on-demand enrichment:

curl -X POST http://localhost:8000/v1/enrichments \
  -H "Authorization: Bearer cai_your_api_key" \
  -d '{"type": "ip", "value": "8.8.8.8"}'

Then check the results:

curl http://localhost:8000/v1/enrichments/ip/8.8.8.8 \
  -H "Authorization: Bearer cai_your_api_key"

Disabling a Provider

Deactivate a provider without deleting it:

curl -X PATCH http://localhost:8000/v1/enrichment-providers/{uuid} \
  -H "Authorization: Bearer cai_your_api_key" \
  -d '{"is_active": false}'

Disabled providers are skipped during enrichment. Existing cached results remain accessible.

Contributing

See Community Integrations for the process of contributing new provider configurations.

Get Started

Concepts

Development

Integrations

Operations

Contributing

Adding Enrichment Providers

Two Ways to Add Providers

Via API (Runtime)

Via Database Seed (Builtin)

HTTP Config Structure

Template Variables

Auth Types

Malice Rules

Operators

Field Extractions

Cache Configuration

Testing Your Provider

Disabling a Provider

Contributing

​Two Ways to Add Providers

​Via API (Runtime)

​Via Database Seed (Builtin)

​HTTP Config Structure

​Template Variables

​Auth Types

​Malice Rules

​Operators

​Field Extractions

​Cache Configuration

​Testing Your Provider

​Disabling a Provider

​Contributing

Two Ways to Add Providers

Via API (Runtime)

Via Database Seed (Builtin)

HTTP Config Structure

Template Variables

Auth Types

Malice Rules

Operators

Field Extractions

Cache Configuration

Testing Your Provider

Disabling a Provider

Contributing