Quickstart

Run the server

The fastest path is the Docker image from the sc repository:

git clone https://git.koehn.com/brad/sc.git
cd sc
docker build -t sc .
docker run --name sc -d -p 5000:5000 sc

For local development, run the PSGI app directly:

cp sc.example.yaml sc.yaml
plackup -r server.psgi

For local concurrency, use Starman:

plackup -s Starman --workers 4 --port 5000 server.psgi

Submit a message

Send the full RFC-822 message, headers and all, in the JSON message field:

jq -n --rawfile message spam.eml '{message: $message}' \
  | curl -s -H 'Content-Type: application/json' \
      --data-binary @- http://localhost:5000

The response groups evidence by abuse contact so you can review who would receive each complaint.

Use the CLI helper

bin/sc is a thin Bash wrapper around the web API. It needs curl and jq.

bin/sc --server http://localhost:5000 spam.eml
SC_URL=http://localhost:5000 bin/sc < spam.eml

Add a trusted boundary override when you need request-local mail boundary settings:

bin/sc --server http://localhost:5000 \
  --boundary '{"name":"mx.example.com"}' \
  spam.eml

Ask for XARF in the response by passing reporter details and a hosted-link type:

bin/sc --server http://localhost:5000 --xarf \
  --xarf-reporter-org "Example Org" \
  --xarf-reporter-contact abuse-reports@example.com \
  --xarf-reporter-domain example.com \
  --xarf-link-type fraud \
  spam.eml

Ask a configured server to send reports with --send-reports or SC_SEND_REPORTS=true:

bin/sc --server http://localhost:5000 --send-reports spam.eml

Most CLI options also have environment fallbacks: SC_URL, SC_BOUNDARY, SC_SEND_REPORTS, SC_XARF_REPORTER_ORG, SC_XARF_REPORTER_CONTACT, SC_XARF_REPORTER_DOMAIN, SC_XARF_SENDER_ORG, SC_XARF_SENDER_CONTACT, SC_XARF_SENDER_DOMAIN, SC_XARF_LINK_TYPE, and SC_XARF_SMTP_SOURCE_PORT.

Generate abuse drafts

bin/sc-compose-abuse reads a message from stdin, calls bin/sc --xarf, and writes one draft email per abuse recipient.

bin/sc-compose-abuse \
  --server http://localhost:5000 \
  --from abuse-reports@example.com \
  --xarf-reporter-org "Example Org" \
  --xarf-reporter-contact abuse-reports@example.com \
  --xarf-reporter-domain example.com \
  --xarf-link-type fraud \
  --output-dir drafts \
  < spam.eml

It sends mail only when you add --send and SMTP settings. SMTP defaults can come from SC_SMTP_HOST, SC_SMTP_PORT, SC_SMTP_USERNAME, SC_SMTP_PASSWORD, SC_SMTP_TLS, SC_SMTP_HELLO, and SC_SMTP_SEND; report-draft defaults can come from SC_REPORT_OUTPUT_DIR, SC_REPORT_FROM, SC_REPORT_REPLY_TO, and SC_REPORT_SUBJECT_PREFIX.