Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Threat Intelligence

CSM tracks, scores, and correlates attacks using a local attack database enriched with external feeds and GeoIP data.

cPanel service-subdomain alerts retain the logged address as unverified context, separate from per-IP reputation and attack history.

Attack Database

  • Per-IP event tracking (brute force, reconnaissance, reputation, authenticated activity)
  • Local scoring from attack volume, types and targeted accounts, used to rank addresses and in the unified verdict; the score never raises a finding or a block on its own
  • Top attackers leaderboard

Successful cPanel, FTP, webmail and PAM login audit events, and authenticated File Manager writes, remain in event history and account counts as auth_success (Authenticated Activity). They add no event-volume or multi-account score. Multi-IP login and authentication-failure signals keep their existing scoring.

file_upload remains readable for historical records; no current check produces it. Existing scores recorded under older classifications are not rewritten because aggregated login counts cannot distinguish ordinary logins from multi-IP alerts. For a confirmed false positive, follow Clearing a stale local threat score. That operation preserves historical events and does not remove firewall or permanent-blocklist entries; review those separately.

Mail evidence

The attack database keeps mail login attacks and spam/ham verdicts in a separate mail section. Equivalent IPv4 and IPv6 spellings share one record; invalid sender addresses are ignored. Spam and ham do not change the local threat score or add attack events. Ham only updates an existing record.

Spam and ham verdicts about an IPv6 sender are recorded per /64 network, not per address. A record that holds only spam evidence is dropped once that evidence has faded, or sooner to keep the 50,000-record spam evidence budget. The budget is checked when a verdict is recorded, using that verdict’s observation time; startup can load more records until then. See Spam evidence for the details.

Verdict weights decay from their observation times, including when older verdicts arrive after newer ones. A missing observation time uses the current time. Spam refreshes the record’s activity time. Remaining ham weight keeps a spam-only record until both spam and ham evidence have faded, but never past the 90-day limit since the last spam verdict or finding. The spam evidence budget can drop it sooner. Retained mail evidence survives a restart with its original counts and observation times.

IP Intelligence

Combines multiple sources into a unified verdict:

SourceData
Local attack DBEvent count, types, score
AbuseIPDBExternal reputation (if API key configured)
RspamdPer-IP rolling history (if controller access configured)
Upstream HTTP cachePanel-side shared score (if reputation.upstream configured)
Permanent blocklistOperator-managed persistent blocks
Free public feedsSpamhaus DROP, blocklist.de, CINS Army
Firewall stateCurrently blocked/allowed status
GeoIPCountry, city, ASN, ISP
RDAPNetwork name, organization (cached 24h)

Verdicts: clean, suspicious, malicious, blocked

Free public feeds

CSM loads cached Spamhaus DROP, blocklist.de, and CINS Army data at startup and refreshes it daily. A failed download keeps that feed’s previous data. These lists supplement local evidence without requiring an AbuseIPDB key.

Spamhaus merged EDROP into DROP, so CSM no longer fetches EDROP. An old <state_path>/threat_db/spamhaus-edrop.txt cache is ignored and can be deleted. Existing firewall blocks, whitelists and findings are unchanged.

Pluggable sources

Threat-intel sources implement a small Source interface (lookup-by-IP returning a score + reason). The aggregator queries every enabled source in parallel, applies per-source weighting, and produces the unified verdict above. Adding a new source means implementing the interface and registering it; no existing source code changes.

Currently shipped:

  • AbuseIPDB (reputation.abuseipdb_key) - external IP reputation feed. CSM caps uncached lookups per cycle and reserves store-backed daily quota before sending requests. While the quota is exhausted (daily budget or an API 429/402 backoff) CSM emits a reputation_quota_exhausted Warning so the degraded coverage is visible; a threat_feed_stale Warning fires when previously downloaded free threat feeds have not refreshed in over 7 days. Persistent conditions remain visible in Findings; alert email and the webhook send each one once, and history records a reminder at most once a day, including across daemon restarts; these coverage warnings never trigger reputation scoring or blocks.
  • Rspamd (reputation.rspamd.*) - per-IP rolling-history signals from the local rspamd controller. Delivered ham dilutes the score, temporary deferrals are neutral, and definitive spam actions count against the sender. Token resolution reads token_env from the process environment at query time. Changing the external environment requires a daemon restart; see credential rotation.
  • Upstream HTTP cache (reputation.upstream.*) - shared panel-side cache of AbuseIPDB or proprietary scores. Useful in fleets: agents pay a bounded local cache hit (cache_ttl_min, default 15 m) instead of hammering the upstream once per agent. CSM temporarily opens a fail-open circuit breaker after repeated upstream failures and lets only one cooldown probe through at a time. Use HTTPS for remote panels; plain HTTP is accepted only for loopback. Wire contract: Upstream threat-intel contract.

Verified crawlers

reputation.bot_verify_enabled verifies claimed crawler User-Agents with static IP ranges first, then strict forward-confirmed reverse DNS. reputation.verified_bots adds operator-defined crawler identities with name, ua_substrings, and one verification method: rdns_suffixes or ip_ranges. With rdns_suffixes the source IP must forward-confirm under a registrable domain (public suffixes and shared-hosting suffixes are rejected; a PTR-only match is not trusted). With ip_ranges the source IP must fall in one of the published CIDRs – this is for crawlers such as GPTBot and PerplexityBot that publish address ranges instead of crawler reverse DNS. Over-broad or non-public ranges are rejected. All checks run at config load and on reload.

Built-in rDNS verification covers Googlebot, Bingbot, Applebot, DuckDuckBot, Amazonbot, the Facebook and Meta crawlers, Brave, and the SERanking backlink bot. Googlebot, Bingbot, and Applebot also match a shipped IP-range snapshot first and fall back to reverse DNS; DuckDuckBot, Amazonbot, Facebook/Meta, Brave, and SERanking are rDNS-only.

Reverse-DNS verification is asynchronous. A newly admitted verification job receives a short, bounded pending window, including time spent waiting in the queue. High-volume traffic in that window can route to the proof-of-work challenge when it is enabled. A full queue, stopped worker, unsupported identity, or expired pending window uses the ordinary flood and scanner controls instead.

DNS failures, missing reverse DNS, and failed cache writes do not prove a spoofed identity. They leave verification unresolved, delay retries, and do not renew pending treatment on each retry. Attempt history is bounded. When it is full, new sources can replace completed entries after their initial cooldown; retries cannot extend that reservation. Live jobs and newly granted pending windows keep their history. If no entry can be replaced, admission is refused until capacity becomes available instead of running untracked lookups. Evicted or expired sources without a persisted missing-PTR record can receive another pending window, but the initial cooldown prevents continuous renewal under churn. Expiry preserves live jobs and their retry delay after completion. A missing PTR suppresses further DNS lookups for one fixed hour in the state database, including across restarts. Scans do not extend that hour. After it lapses, DNS retries resume, but the record remains as attempt history for a day, so a restart or in-memory eviction cannot grant fresh pending treatment. Records older than that are removed as new ones are written. Cleanup is attempted at most once an hour, including after a failed cleanup. A definitive verification result replaces that history. The record is not a verdict: it grants neither the verified-crawler exemption nor pending treatment, and it never counts as a spoof. csm store reset-bot-verify and a verified_bots change clear these records together with the cached results. A confirmed negative remains eligible for spoof detection. A cached positive receives the normal verified-crawler exemption.

GPTBot, ChatGPT-User, OAI-SearchBot, PerplexityBot and ClaudeBot are recognized out of the box: their published IP ranges ship as an embedded snapshot and are refreshed from the vendor endpoints by an auto-updater (reputation.bot_ranges, default on, outbound HTTPS, configurable interval; restart required for setting changes). Fetched ranges are validated with the same over-broad and non-public guards as operator entries, and the embedded snapshot is the trusted fallback when a fetch fails. Anthropic publishes one combined feed for ClaudeBot, Claude-User and Claude-SearchBot and documents IP-list verification rather than reverse DNS, so CSM verifies ClaudeBot by address from that feed; the legacy anthropic.com reverse-DNS suffix is kept only as a fallback.

csm update-bot-ranges refreshes these ranges on demand (mirroring csm update-geoip): it fetches the vendor feeds, writes the on-disk snapshot, and asks the running daemon to apply them without a restart. The auto-updater and the manual command both export metrics – refresh success/failure, prefix count per crawler, and the last successful refresh time – under the csm_botranges_* names.

Abuse Reporting

reputation.report can send minimized confirmed-abuse reports to a central database or private collector. It is off by default. Remote targets must use HTTPS; plain HTTP is accepted only for loopback collectors. Keys and target wiring are read at daemon startup, so changes to this block require a restart. The central abuse database accepts ed25519 targets only; its report URL ends in /report and its scored-set URL in /decisions. The request format is in the Abuse Report Contract.

Reported findings

Each class covers these checks. Only Critical findings are reported, except bad_asn_egress and spam, which report High findings too.

ClassChecks
bruteforcepam_bruteforce, wp_login_bruteforce, xmlrpc_abuse, ftp_bruteforce, smtp_bruteforce, mail_bruteforce, admin_panel_bruteforce
credential_stuffingcredential_stuffing
php_relayemail_php_relay_abuse
bad_asn_egressbad_asn_outbound
spammail_spam_source

Nodes accept spam entries in downloaded central lists. With spam in reputation.report.classes, a node raises mail_spam_source for a sender that rspamd keeps rejecting and that has sent it no clean mail recently, and reports that sender. Dry-run antispam nodes count their verdicts too. The finding never blocks or challenges the sender on the reporting node.

Shared mail services are never reported: Google, Microsoft, Amazon SES, SendGrid, Mailgun, Brevo, Yahoo and iCloud. CSM reads their sending hosts from each provider’s published SPF records and refreshes the list in the background. Spam reports wait while that list cannot be loaded. When a refresh has failed and the list is not current, CSM raises a shared_senders_stale Warning. It stays in Findings until the list is current again. Alert email and the webhook send it once; history records a reminder at most once a day, including across daemon restarts.

CSM keeps sender history across restarts. If that history cannot be read at startup, spam source detection stays off for that run and the daemon log says why. A restart turns it back on once the state database can be read.

The class needs email_protection.antispam.enabled. Turning either on or off takes a restart.

A report carries only the source address, the class, a count and the time. List the classes to send in reputation.report.classes. An empty list keeps reporting off.

Set up the central abuse database

  1. On the node, generate a key pair:

    csm report enroll
    

    It prints a 64-byte private key as 128 hex characters and a 32-byte public key as 64 hex characters. Put the private key in the CSM environment file described in credential rotation, for example as CSM_REPORT_KEY. The private key is a secret: never paste it into a ticket or chat. Give only the public key to the central operator.

  2. The central operator approves the node and returns its node_id and key_id, the report and scored-set URLs, and the central public key. Add the central public key, encoded as 64 hex characters, to the same environment file, for example as CSM_CENTRAL_PUBKEY.

  3. Configure the target. The central block is optional; it is described below.

    reputation:
      report:
        enabled: true
        classes: [bruteforce, credential_stuffing, php_relay, bad_asn_egress]
        targets:
          - name: central
            url: https://abuse.example.net/report
            transport: ed25519
            node_id: "<node_id from the operator>"
            key_id: "<key_id from the operator>"
            key_env: CSM_REPORT_KEY
      central:
        enabled: true
        set_url: https://abuse.example.net/decisions
        pubkey_env: CSM_CENTRAL_PUBKEY
        auth_target: central
        action: challenge
    
  4. Restart CSM: systemctl restart csm.service.

reputation.central pulls the database’s signed list of scored addresses. With action: challenge, a qualifying local attacker finding for an unprotected listed address adds it to the challenge list. This requires challenge.enabled: true, an active firewall and a working challenge setup.

With action: block_if_local_corroborated, CSM attempts a block instead once the central score reaches reputation.central.block_threshold; below that score it still uses the challenge path. A live block also requires an active firewall, auto_response.enabled: true, auto_response.block_ips: true and auto_response.dry_run: false, and remains subject to the normal block protections. Dry-run records what would have been blocked. Central data alone never blocks. An ip_reputation match is outside intelligence too, so it never counts as the local finding for either action. action: off pulls the list without taking central-driven actions.

auth_target names the report target whose node key signs each download. The central abuse database refuses unsigned downloads. The target must use transport: ed25519, and its URL must share scheme, host and port with set_url, so a signed request never goes to another host. Leave auth_target unset only for a central service that serves the list without signatures.

Signed downloads work with reputation.report.enabled: false; keep the target configured even when the node does not send reports. csm validate refuses an auth_target that names no target or several, a target that is not Ed25519 or lacks node_id, key_id or key_env, or a set_url on another origin, and CSM will not start with that config. The settings page refuses the same changes. If the target’s key is unset or invalid, CSM starts with the central consumer off and logs one line naming reputation.central.auth_target. It never falls back to unsigned downloads while auth_target is set.

If the service refuses a download, CSM keeps its last verified list, tries again at the next refresh, and logs central-intel: pull unauthorized; check node enrollment, node clock and reputation.central.auth_target. Each successful refresh logs central-intel: refresh complete (version=N).

To rotate the node key, run csm report enroll again and have the central operator register the new public key. Then update key_id and the environment file, and restart CSM.

Send to a private collector

Use transport: hmac with a shared secret. You choose node_id and key_id; the collector uses them to find the secret. Set the named secret and optional token in CSM’s environment file and restart CSM. The secret is used as raw string bytes, not hex-decoded.

reputation:
  report:
    enabled: true
    classes: [bruteforce, credential_stuffing]
    targets:
      - name: collector
        url: https://collector.example.net/csm/report
        transport: hmac
        node_id: web-01
        key_id: k1
        key_env: CSM_COLLECTOR_SECRET
        token_env: CSM_COLLECTOR_TOKEN   # optional bearer token

The collector must implement the Abuse Report Contract. CSM queues one copy per target, so one node can report to the central database and a private collector at the same time. Give each target a unique, stable name: duplicate names select only the last usable target, and removing or renaming a target, or a key error that makes it unusable at startup, discards its queued reports on the next delivery pass. The spool_max capacity is shared across all targets, not reserved per collector. Overflow drops the oldest entries across that shared queue.

Check delivery

When reporting starts successfully, the log shows abuse-reporting: enabled for 1 target(s), 4 class(es) with your counts. A target with a missing field, a non-HTTPS remote URL, an unknown transport or an unusable key is skipped with a log line. Reporting stays off when no usable targets or valid classes remain, or when its spool cannot be opened. Failed deliveries are logged as reporting: delivery incomplete. The abuse_reporting.ingress and abuse_reporting.spool entries in protection queue health show waiting and lost reports.

Delivery and retries

Reports wait in a durable queue and are delivered once a minute. When a target is down, throttling, or refuses the node (for example before the node is approved, or when the node’s clock is wrong), that target’s reports stay queued in order and it is retried a minute later; other targets keep receiving theirs. A target that answers HTTP 429 with Retry-After, in seconds or as an HTTP date, is retried after that wait instead, up to an hour. Throttling while the target still accepts reports is not logged. If it keeps throttling without accepting any, the delay doubles on each attempt up to a minute, or the requested wait if longer, with a warning at most once a minute per target. A report the collector refuses as invalid (HTTP 422) would be refused again, so it is dropped and counted as lost.

Reporting and central intelligence actions share the address protection checks. These cover literal infrastructure IPs/CIDRs and crawler IP ranges, not infrastructure hostname resolution or rDNS crawler results. For NAT64 and 6to4 sources, protection of either the original IPv6 address or its embedded IPv4 address applies.

Web UI

The Threat Intel page (/threat) provides:

  • IP lookup with composite scoring
  • Two separate block actions per IP: a 24 hour block and a confirmed permanent block, singly or over a selection of attackers
  • Top attackers with GeoIP enrichment
  • Attack type breakdown chart
  • Hourly trend chart
  • Whitelist management (permanent and temporary)

A 24 hour block records threat evidence that expires with the firewall block, so a mistaken block of a customer address stops counting against it once the block lapses. A permanent block records evidence that stays until an operator clears it. When an address is no longer blocked but still holds permanent evidence, the lookup says so, because that address is flagged again the next time it is seen.

The 24 hour action refuses to shorten an existing permanent or longer firewall block. Unblock explicitly before changing that lifetime. Bulk requests skip those addresses and report warnings. Existing permanent threat evidence remains until cleared; feed updates do not remove a timed operator record before its expiry.

Bulk undo restores each prior firewall lifetime, using the original deadline for timed blocks. Expired blocks stay expired, and a later block, clear, or whitelist decision invalidates the older undo action. Only successful firewall reversals restore the corresponding threat evidence.

When CSM starts it drops the attack records of addresses inside the top-level infra_ips list, so an internal host listed after it was recorded stops ranking as an attacker. Only addresses and CIDRs count; hostnames and firewall.infra_ips do not. Event history is kept.

Unblock & Clear accepts private addresses for an internal host that is not in infra_ips. Clear and whitelist remove the attack record under every equivalent spelling of the address, such as an IPv4-mapped form. Whitelist and allow actions refuse private addresses and point to infra_ips instead.

API Endpoints

GET  /api/v1/threat/stats            Attack stats and type breakdown
GET  /api/v1/threat/top-attackers    Top attacking IPs with GeoIP
GET  /api/v1/threat/ip               IP threat lookup
GET  /api/v1/threat/events           IP event history
GET  /api/v1/threat/whitelist        Whitelisted IPs
GET  /api/v1/threat/db-stats         Attack database statistics
POST /api/v1/threat/block-ip         Block IP for 24 hours
POST /api/v1/threat/block-ip-permanent  Block IP with no expiry
POST /api/v1/threat/whitelist-ip     Permanent whitelist
POST /api/v1/threat/temp-whitelist-ip  Temporary whitelist
POST /api/v1/threat/clear-ip         Clear from attack DB
POST /api/v1/threat/unwhitelist-ip   Remove from whitelist