Configuration

The server loads YAML configuration from sc.yaml in its working directory. Set SC_CONFIG to use another path.

SC_CONFIG=/etc/sc/sc.yaml plackup -r server.psgi

Trusted boundary

trusted_boundary tells sc which receiving mail server marks the edge of your mail system. If configured, sc reports the public remote IP that handed mail to that boundary. This helps avoid reporting internal or downstream hops.

trusted_boundary:
  name: mx1.example.com
  domain: example.com
  cidrs:
    - 203.0.113.0/24
    - 2001:db8:1234::/48

If no trusted boundary is found, Received-header reports are skipped to reduce false positives. If trusted_boundary is not configured at all, sc preserves its older behavior of reporting every public IP it can parse from Received headers.

Cache backends

Abuse-contact lookups can be slow, so sc caches normalized CIDR results. The default memory backend is fine for local development and single-worker deployments.

cache:
  backend: memory
  namespace: sc:abuse-cache
  expiration_time: 3600
  cleanup_interval: 3600

Use Redis or Memcached when multiple workers should share cached lookups.

cache:
  backend: redis
  namespace: sc:abuse-cache
  expiration_time: 3600
  redis:
    server: 127.0.0.1:6379

cache:
  backend: memcached
  namespace: sc:abuse-cache
  expiration_time: 3600
  memcached:
    servers:
      - 127.0.0.1:11211

Link handling

ignored_link_hosts suppresses complaints for no-fault link hosts such as public font or JavaScript CDNs.

ignored_link_hosts:
  - fonts.googleapis.com
  - cdn.jsdelivr.net

url_shorteners_to_follow controls which short-link hosts are expanded before link reports are generated. Omit it to use built-in defaults, set it to [] to disable network shortener expansion, or add hosts to merge with the defaults.

url_shorteners_to_follow:
  - bit.ly
  - tinyurl.com

XARF and SMTP sending

The API can include XARF reports in responses. The server can also compose and send abuse report email when abuse_report is configured and the request explicitly includes {"abuse_report":{"send":true}}.

abuse_report:
  from: abuse-reports@example.com
  reply_to: abuse-reports@example.com
  subject_prefix: Spam abuse report

  xarf:
    reporter:
      org: Example Org
      contact: abuse-reports@example.com
      domain: example.com
    link_type: fraud

  smtp:
    host: smtp.example.com
    port: 587
    username: abuse-reports@example.com
    password: secret
    tls: starttls
    hello: sc.example.com

from, xarf.reporter.org, xarf.reporter.contact, xarf.reporter.domain, xarf.link_type, and smtp.host are required. reply_to, subject_prefix, xarf.sender, xarf.smtp_source_port, SMTP auth, and smtp.hello are optional.

smtp.tls may be none, starttls, or smtps. The port defaults to 465 for smtps and 587 otherwise. If either smtp.username or smtp.password is set, both must be set.

Server-side sending is synchronous during the request. Individual recipient failures are reported per recipient and per delivery in the response.

Delivery dispositions

Delivery dispositions let the server change where a complaint goes after sc has found the original RDAP abuse contact. They apply only when server-side sending is requested with abuse_report.send: true.

Aliases

Use abuse_report.aliases when a provider publishes one abuse mailbox in RDAP but wants reports delivered somewhere else. Alias keys are the final recipient address; values are the original RDAP abuse contact to replace.

abuse_report:
  aliases:
    trust-and-safety@amazonaws.com: abuse@amazonaws.com
    mail-abuse@google.com: network-abuse@google.com

Matching is case-insensitive. The response complaints map is keyed by the final recipient, while each complaint still preserves the original whois-abuse-email evidence.

Cloudflare API routes

Use abuse_report.api_routes to submit matching complaints through a provider API instead of SMTP. Cloudflare is the supported provider.

abuse_report:
  api_routes:
    - provider: cloudflare
      match_original_abuse_email: abuse@cloudflare.com
      account_id: cloudflare-account-id
      api_token_env: SC_CLOUDFLARE_API_TOKEN
      report_param: general
      act: abuse_general

match_original_abuse_email is matched against the original RDAP abuse contact, not the alias recipient. account_id is the Cloudflare account ID. api_token_env names an environment variable that must contain the Cloudflare API token when the server handles a send request.

report_param defaults to general and becomes the final path segment in Cloudflare’s /abuse-reports/{report_param} endpoint. act defaults to abuse_general and is sent in the Cloudflare JSON payload.

Cloudflare routes currently handle link complaints only. Matching Received-header complaints remain on the normal SMTP path. If a Cloudflare API submission fails, the HTTP request still returns 200, abuse_report.sent is false, and the API delivery entry includes the failure; sc does not fall back to SMTP for that link complaint.

For backward-compatible config layouts, aliases and api_routes may also be nested under abuse_report.dispositions, but the top-level abuse_report.aliases and abuse_report.api_routes form is preferred.