Security Policy API

The legacy Security Policy API configured one action per alert type for the whole organization. Policies replace that with a baseline preset plus explicit rules for everything that deviates from it. This page shows the legacy shapes and how to reproduce them.

Legacy Shapes

GET /orgs/{org_slug}/settings/security-policy

Takes an optional custom_rules_only query parameter; set it to true to get only the alert types you customized.

{
  "securityPolicyRules": {
    "malware": { "action": "error" },
    "criticalCVE": { "action": "error" },
    "installScripts": { "action": "warn" },
    "unpopularPackage": { "action": "ignore" }
  },
  "securityPolicyDefault": "medium"
}

POST /orgs/{org_slug}/settings/security-policy

Body accepts policyDefault, policyRules, and resetPolicyRules. The response has the same shape as the GET.

{
  "policyDefault": "medium",
  "policyRules": {
    "installScripts": { "action": "warn" }
  }
}

Actions are error, warn, monitor, ignore, and defer, where defer means "fall back to the default policy". In the new model defer needs no translation — the baseline preset is the default.

How to Think About the Conversion

The legacy map and a policy are not the same shape, so the conversion is not field-by-field:

1. Pick the baseline preset that matches most of your configuration — see Baseline Presets for the exact action each preset applies per alert type.
2. Write a rule for every alert type where you deviate from that preset. Alert types where your legacy action already matches the baseline need no rule at all.
3. Actions carry over directly: error, warn, monitor, and ignore mean the same in both systems.

Example: Before and After

Say your legacy policy blocks critical CVEs, warns on install scripts, and ignores unpopular packages:

{
  "securityPolicyRules": {
    "criticalCVE": { "action": "error" },
    "installScripts": { "action": "warn" },
    "unpopularPackage": { "action": "ignore" }
  }
}

The Balanced baseline already blocks malware and warns on typosquats, but it only warns on critical CVEs, doesn't cover install scripts at all, and merely monitors unpopular packages — so all three of your customizations need rules. The equivalent setup is three calls.

Set the baseline on the Default policy:

curl -u "$SOCKET_API_TOKEN:" -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "baseline": "balanced" }' \
  https://api.socket.dev/v0/orgs/$ORG/alert-policies/default

Then add one rule per deviation:

curl -u "$SOCKET_API_TOKEN:" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block critical CVEs",
    "action": "error",
    "vigil_selector": { "finding.alertType": "criticalCVE" }
  }' \
  https://api.socket.dev/v0/orgs/$ORG/alert-policies/default/rules

curl -u "$SOCKET_API_TOKEN:" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warn on install scripts",
    "action": "warn",
    "vigil_selector": { "finding.alertType": "installScripts" }
  }' \
  https://api.socket.dev/v0/orgs/$ORG/alert-policies/default/rules

curl -u "$SOCKET_API_TOKEN:" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ignore unpopular packages",
    "action": "ignore",
    "vigil_selector": { "finding.alertType": "unpopularPackage" }
  }' \
  https://api.socket.dev/v0/orgs/$ORG/alert-policies/default/rules

Each POST returns 201 with the stored rule, including its full selector and rank. See Vigil Selectors for everything a selector can express.

Reading the Equivalent Back

GET /orgs/{org_slug}/alert-policies returns the default policy first, followed by custom policies in creation order, and GET /orgs/{org_slug}/alert-policies/{policy_id}/rules returns { "items": [ ... ] } in evaluation order. Together with the policy's baseline field, that is the full picture the legacy GET used to give you in one response. The default policy's id is the literal string default until it is first modified, after which it becomes a UUID — but default remains accepted as the policy_id in every policy and rule endpoint regardless.

PUT /orgs/{org_slug}/alert-policies/{policy_id} accepts name, description, repository_ids, and baseline. Only the fields you send change, and repository_ids replaces the entire set. DELETE removes the policy, its rules, and its label, and its repositories fall back to the default policy. The default policy cannot be renamed or deleted.

Related Pages

• Alert Triage API — the other half of the legacy configuration.
• Baseline Presets — the per-alert-type actions of every preset.
• Updating API Integrations — endpoint mapping and token scopes.