Cooldown

Most malicious releases are caught and pulled within days. A cooldown refuses any package version younger than a window you choose, which gives the community that time. Versions release automatically once they age past the window. Nothing on the firewall changes: it enforces whatever action Socket returns for the recentlyPublished alert.

Before you start: a running firewall (Block installs with Firewall).

1. Set the window

Dashboard → Settings → Alerts → Scans → Recently Published Alert Threshold.

🚧

The default is 0

At 0 the alert is disabled and nothing is held. Set a non-zero value in days or hours (for example, 4 days). The threshold is not configured in the firewall, and there is no API for it.

2. Set the action to Block

The firewall only blocks when the alert's action is Block. How you set it depends on which policy system your organization is on.

Policies (organizations migrated to the new system): open the Default policy and add a rule for the Recently published alert type with action Block. The firewall always uses the Default policy, because installs are not tied to a repository.

Security Policy (legacy): Dashboard → Settings → Security Policy → Recently published → Block.

3. Test it

Find a version published today, and confirm Socket flags it before involving the firewall.

# Newest rollup version and its publish time
curl -s https://registry.npmjs.org/rollup \
  | jq -r '.["dist-tags"].latest as $v | "\($v)  \(.time[$v])"'

# Socket's verdict: expect a recentlyPublished alert with action "error"
curl -s -X POST "https://api.socket.dev/v0/purl?alerts=true" \
  -H "Authorization: Bearer $SOCKET_API_KEY" -H 'Content-Type: application/json' \
  -d '{"components":[{"purl":"pkg:npm/rollup@NEW_VERSION"}]}' \
  | jq -c 'select(.name!=null)|[.alerts[]?|select(.type=="recentlyPublished")|.action]'

If this prints [], the threshold hasn't taken effect yet. Open the setting and save it again, then re-check. Once it prints ["error"], test through the firewall:

for v in NEW_VERSION 4.21.0; do
  printf 'rollup@%s -> ' "$v"
  curl -sk -D- -o /dev/null \
    "https://sfw.example.com/npm/rollup/-/rollup-$v.tgz" \
    | grep -iE '^HTTP/|^x-socket-block-reason' | tr '\n' ' '; echo
done

Replace NEW_VERSION with the version from the first command. If the newest version is already older than your window, try another busy package such as zod or vite.

Expected output

[email protected] -> HTTP/2 403 x-socket-block-reason: Recently published
[email protected] -> HTTP/2 200

Release one version early (waiver)

A waiver is a package-scoped exception for the recentlyPublished alert. Pin the version: a wildcard waives every future release of that package too.

Policies: in the Default policy, add a rule above the cooldown rule matching the package, the version, and the Recently published alert type, with action Ignore. Or resolve the alert from the alert view with a reason (see Resolve Alerts).

Security Policy (legacy): Settings → Security Policy → Alert Triage, add an entry for the package, version, and Recently published, set to Ignore.

🚧

Waivers take up to 10 minutes to reach the firewall

The Socket API reflects the waiver within seconds, but the firewall keeps serving its cached 403 until cache.ttl expires (600 s by default). Tell the requester to wait 10 minutes, or clear the cache: restart the container, or run FLUSHDB if you use Redis, where verdicts survive restarts.

Agree on a note format (ticket number and approver) before you start. The audit log records who made the change and when, but the justification is only what the approver typed.

Verify

• Threshold is non-zero
• A version younger than the window returns 403 with Recently published
• An older version of the same package returns 200
• A waived version returns 200 after the cache expires; other new versions stay blocked

Optional: allow recent versions for some ecosystems

To let recent versions through for selected ecosystems, add them to the existing socket: block in socket.yml (don't start a second socket: key) and recreate the container. Ecosystems not listed keep the Block action.

socket:
  api_url: https://api.socket.dev
  fail_open: true
  recently_published_enabled_ecosystems:
    - npm

Listed ecosystems are allowed: the client gets 200 with x-socket-decision: allowed and no warning in its install output. The event in logs, webhooks, and Splunk records decision: allowed with action: error, and is logged at error level. Count blocks in your SIEM on decision, not action, or these allows will look like blocks.

Automate it

The threshold itself has no API; set it in the dashboard. Waivers can be scripted.

Policies

The token needs alert-policy:list and alert-policy:create (rules) or alert-resolution:create (resolutions). The firewall's own token does not have these.

ORG=your-org
DEFAULT_ID=$(curl -s -H "Authorization: Bearer $SOCKET_API_KEY" \
  "https://api.socket.dev/v0/orgs/$ORG/alert-policies" \
  | jq -r '.. | objects | select(.apply_method? == "unlabeled_repos") | .id' | head -1)

# Waiver as a policy rule (new rules are placed first). Add ?dry_run=true to test.
curl -s -X POST -H "Authorization: Bearer $SOCKET_API_KEY" -H 'Content-Type: application/json' \
  "https://api.socket.dev/v0/orgs/$ORG/alert-policies/$DEFAULT_ID/rules" \
  -d '{"name":"Cooldown waiver rollup NEW_VERSION",
       "vigil_selector":{"artifact.type":"npm","artifact.name":"rollup","artifact.version":"NEW_VERSION",
                         "finding.alertType":"recentlyPublished"},
       "action":"ignore",
       "note":"Waiver TICKET-123, approved by NAME"}'

# Or as an alert resolution. reason is required:
# false_positive | remediated | tolerable_risk | other
curl -s -X POST -H "Authorization: Bearer $SOCKET_API_KEY" -H 'Content-Type: application/json' \
  "https://api.socket.dev/v0/orgs/$ORG/alerts/resolutions" \
  -d '{"vigil_selector":{"artifact.type":"npm","artifact.name":"rollup","artifact.version":"NEW_VERSION",
                         "finding.alertType":"recentlyPublished"},
       "reason":"tolerable_risk",
       "comment":"Waiver TICKET-123, approved by NAME"}'

Security Policy (legacy)

# Set recentlyPublished to Block
curl -s -X POST -H "Authorization: Bearer $SOCKET_API_KEY" -H 'Content-Type: application/json' \
  https://api.socket.dev/v0/orgs/your-org/settings/security-policy \
  -d '{"policyRules":{"recentlyPublished":{"action":"error"}}}'

# Waiver as a triage entry. Returns {"result":"success"}
curl -s -X POST -H "Authorization: Bearer $SOCKET_API_KEY" -H 'Content-Type: application/json' \
  https://api.socket.dev/v0/orgs/your-org/triage/alerts \
  -d '{"alertTriage":[{"packageType":"npm","packageNamespace":"*","packageName":"rollup",
       "packageVersion":"NEW_VERSION","alertType":"recentlyPublished","state":"ignore",
       "note":"Waiver TICKET-123, approved by NAME"}]}'

Reference

• Cool-down policy
• Per-ecosystem recentlyPublished downgrade