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

Auto-Response

When enabled, CSM automatically responds to detected threats. All actions are logged in the audit trail.

Actions

ActionDescription
Kill processesFake kernel threads, reverse shells, GSocket, loops that write back a file CSM removed, and shell loops a web request left running in the background. Never kills root or system processes.
Quarantine filesMoves webshells, backdoors, phishing to /opt/csm/quarantine/ with full metadata (owner, permissions, mtime). Restoreable from the web UI.
Block IPsAdds attacker IPs to the nftables firewall with configurable expiry. Admission uses auto_response.max_blocks_per_hour (default 2000/hour); legacy scan blocking defaults to 50/hour.
Clean supported malwareApplies bounded PHP and .htaccess cleaners with pre-clean backups. Database cleanup has a separate opt-in.
Drop malicious DB objectsWhen clean_database is on, confirmed-malicious stored triggers/events/procedures/functions are dropped after a SHOW CREATE backup is recorded, so the drop is reversible. Detection runs regardless; the drop is gated on the operator opt-in.
PHP shieldBlocks PHP execution from uploads/tmp directories and inspects directly executed wp-content scripts for request-fed command sinks and packed eval loaders.
PAM blockingInstant IP block when one address breaches thresholds.pam_bruteforce_threshold SSH failures inside pam_bruteforce_window_min minutes, or fails SSH logins against cred_stuffing_distinct_accounts distinct accounts. Only successful SSH logins clear those failures; failures from other PAM services never block.
Subnet blockingAuto-blocks IPv4 /24 or IPv6 /64 when 3+ IPs from the same range were blocked within netblock_window (7 days by default). Currently blocked addresses count regardless of age, including operator and permanent blocks. Ended blocks count while their latest observed block start is inside the window, unless an earlier subnet block already answered them. A returning operator block starts fresh history after its absence is observed. Whitelist and clear actions, including bulk whitelist, forget the address.
Permblock escalationPromotes temporary blocks to permanent after N repeated offenses.
Suspend mailboxAfter confirmed credential abuse, attempts to suspend that mailbox’s logins and outgoing mail through cPanel. Either success stops escalation; the account-wide outgoing mail hold is the fallback when both fail, no account owns the domain, or the target is a bare domain. A Critical mail_account_compromised (a login after brute force) also suspends the mailbox. When that login is the cPanel account’s own username, the account’s outgoing mail is held instead, because that password unlocks every mailbox. A stolen login never falls back to the account hold: a failed suspension raises a Critical email_mailbox_response finding, as does each suspension or hold it applies. Signs of compromise that add up for one mailbox suspend it with a single Critical email_mailbox_compromise finding; see Mailbox Compromise Evidence. All of these follow auto_response.enabled and dry-run, and each attempted suspension or hold is recorded in the action log with its quoted release command.
Auto-freeze (PHP relay)On cPanel, freezes active Exim messages attributed to a high-confidence PHP-relay finding. It has its own dry-run control and action-rate limit. See PHP-relay CLI.

Of the processes a web request left running, only shells are stopped; anything else, including a non-shell parent of a shell, stays a Warning for review.

Mailbox suspension runs /usr/local/cpanel/bin/uapi as a transient systemd service outside the daemon’s filesystem sandbox; hosts without a usable systemd-run run it directly. Each call is bounded in time, the JSON result decides success, and mailbox names stay literal arguments on both paths.

Partial suspensions name the restriction that succeeded; they do not claim both logins and sending stopped. Mailbox restrictions and account holds already applied outside CSM are not offered for release. If cPanel cannot report the mailbox state, CSM suspends anyway and records the suspension as its own; sending evidence can still fall back to an account hold.

After resolving the credential abuse, release the mailbox or account on the Email page, Suspended tab. The tab lists every suspension and hold CSM made with its live state in cPanel; one lifted directly in cPanel shows as released outside CSM. Incomplete or unreadable status stays unknown, and a delayed status response cannot release a newer suspension.

Release undoes the recorded restrictions and never changes a password. Evidence captured before the release cannot suspend the mailbox again. Cleanup failures are reported so the release can be retried.

Releasing an account hold delivers the mail cPanel held, so delete spam from the Queue tab first; the confirm says so. The action log also keeps the release commands, quoted for the shell, for example /usr/local/cpanel/bin/uapi '--user=account' Email unsuspend_login 'email=alice%40example.com' and the matching unsuspend_outgoing command. The address is URI-encoded because uapi decodes its values.

WHM holds and releases check the JSON API result before reporting success. Dry-run writes one planned-action record without running a command; disabled auto-response writes none.

Subnet history is pruned hourly and saved only when it changes. If the file cannot be read it is left untouched and escalation counts only the addresses blocked right now until it is repaired or removed; status and doctor report the failure. Clear, whitelist and flush actions report history cleanup failures so operators can retry them.

Mail login spray blocks of IPv4 addresses do not contribute to /24 escalation. IPv6 spray blocks count toward their /64 like any other block, since one /64 is treated as one source. The classification comes from committed firewall state, so a missing or stale scan tracker does not turn IPv4 spray blocks into range evidence. Saved spray blocks absent from the kernel do not count as active blocks. If block metadata cannot be read, subnet escalation waits while individual block attempts continue.

Blocks of an address on c2_blocklist never count toward subnet escalation or permanent promotion, whatever finding asked for them: a listed command-and-control server is where local processes connect, not a source of attacks. Other blocked addresses in its subnet still count.

Process termination

An eligible finding receives one automatic termination evaluation across scan and alert delivery. A refused or failed attempt is not retried when the same finding reaches alert delivery. Realtime findings still receive an evaluation; new detections and findings replayed from storage receive a fresh evaluation.

CSM opens a kernel process handle before verifying ownership, executable, start time, or the file referenced by a process. It checks that the captured process is still alive after verification and sends the signal through that handle. An exited process cannot redirect the signal to a replacement with the same PID. Automatic and manual malware termination reject root credentials, including effective and saved root IDs. The separate opt-in AF_ALG reaction requires the current credentials and executable to match its recorded event.

Safe signaling needs pidfd_send_signal (Linux 5.1). Where pidfd_open (Linux 5.3) is absent – EL8 and CloudLinux 8 ship 4.18 kernels without it – CSM pins the target through its /proc/<pid> directory descriptor, which pidfd_send_signal accepts and which refers to the same kernel process. Both paths reject a recycled PID; CSM never falls back to numeric PID signaling. On a kernel without pidfd_send_signal, or when service restrictions deny the call, termination stays disabled: csm doctor reports process termination supported as failed and the health status becomes degraded whenever auto_response.kill_processes is enabled, so an inoperative protection is visible before an incident needs it. Each health snapshot probes this capability again, so transient resource failures clear once signaling becomes available. Automatic termination failures are logged while the original detection remains. Manual kill-and-quarantine reports a termination failure even if the file was successfully quarantined; inspect both the process and recovery entry before retrying. Manual request cancellation is checked before sending a signal.

Automatic file response limits

Realtime quarantine, scheduled quarantine, PHP cleaning and automatic .htaccess cleaning share one rolling-hour budget. auto_response.max_file_actions_per_hour caps host-wide attempts (default 50), max_file_actions_per_account_per_hour caps attempts for one account (default 10), and max_file_action_failures_per_hour pauses these responses after repeated failures (default 3). Zero or an omitted key uses the default; negative values and values above 10000 are rejected.

Each attempt is reserved before touching the file. Successful, failed and interrupted attempts all consume capacity. Reservations live in <state_path>/file-response.json and survive configuration reloads and daemon restarts. Entries expire one hour after admission. A backwards clock adjustment keeps future-dated reservations charged until their window has passed.

Account budgets come from the target’s account-home path, not finding text. Paths outside recognized account homes share an unknown-account budget. One account reaching its limit does not stop other accounts unless the host or failure limit is also reached. Automatic directory and special-file quarantine is refused because one directory move can affect an unbounded number of files. Manual remediation remains available after reviewing the original detection.

A brief shared lock protects each safety reservation and outcome update. The file action runs after reservation without holding that lock, so a slow copy does not block another available slot. Pending actions hold failure capacity until their outcome is saved, so concurrent failures cannot pass the configured ceiling. If the state lock remains busy, the next attempt is refused. Unreadable, incomplete or unwritable safety state also refuses mutations. The original detections remain visible, and a deduplicated auto_response_paused warning reports the cause. Account-limit notices are grouped at host scope so a fault across many accounts cannot flood the alert budget. A pause does not create a retry job; new eligible detections can act after capacity returns. Review outstanding findings and recovery evidence before manual remediation. Do not delete safety state to clear a pause; repair storage faults and let reservations expire.

Duplicate detections of one stable file version share a single realtime response attempt. A different file planted at the same path remains eligible. Within one daemon run, alert delivery does not repeat a file response already evaluated by a scan or admitted to the realtime safety gate, including budget refusals. A realtime detection rejected using sampled content remains eligible for full-file validation during delivery. The original findings still reach alerts and history; a new detection can be evaluated again. Findings still queued at shutdown retain the existing restart replay behavior: the next daemon run evaluates them again under the same persisted limits. Parked findings also keep the offending subnets and targeted accounts needed for subnet response and credential spray correlation. Older parked findings replay without that data. The subnets also appear in the public cidrs field.

Critical realtime PHP findings that prove request data reaches an execution primitive, or that executable PHP unwraps and runs encoded content, enter this file-response gate immediately. Quarantine holds an exclusive Linux lease on the open file that produced the finding until that file is removed. It refuses while another process has the file open or is running it, and when the content or path identity changes. Whole-file malware identified by the cleaner uses this lease too. Other quarantines do not take this lease, so they can still move a file that is open or running. Comment-only matches, URL-only droppers, filename-only checks, tail-window matches and YARA-only findings remain available for review without an automatic move.

File quarantine copies only the file size it verified and checks the file again before removing it. A file that changed is restored and its copy discarded. If its name was recreated meanwhile, the error names the private directory that holds the changed file.

Parked reputation findings keep their intelligence source and expiry. If an expiry cannot be encoded, only that intelligence metadata is dropped; the finding and the rest of the queued batch are still saved and replayed. This handling is automatic and has no setting.

A failed PHP cleaner leaves the file and any pre-clean backup for manual review. It no longer escalates to whole-file quarantine. A cleaner that recognizes no injection or declines an unsupported target refuses the file instead of failing. Sources that change or disappear before mutation are also refusals, including socket replacements and parent paths replaced after quarantine copying. These attempts still use capacity but do not count toward the failure pause. Read, write, backup and durability errors still count as failures. Quarantine and cleaners retain their descriptor-based identity checks, and automatic actions revalidate the file after saving the reservation. Opening a replacement special file cannot block response processing.

Manual full scans leave cleaner refusals for review instead of reporting a failed remediation. csm clean also distinguishes a refusal from an action failure; both return a nonzero exit status when the file was not cleaned.

WordPress core, plugin and theme files are cleaned in place, with three exceptions. When cleaning would leave nothing of a file that sends no page output, the file is quarantined whole: a stub would lose the same content, while quarantine keeps it for a restore. When cleaning would erase a file’s page output, the file stays untouched for review. When the release of WordPress core or of a wordpress.org plugin that a site runs does not ship the file, it was planted and is quarantined. CSM trusts the release a site names only when its version.php or <slug>.php plugin main file is that release’s own copy, and only from the checksums the realtime file monitor has cached. A plugin whose main file has another name stays with the cleaner. Page output is any text outside PHP code, including short and echo tags. Whole-file quarantine rechecks the original content under the same protection used for other verified file responses; a changed file stays in place. csm clean refuses a file it would leave empty.

Automatic permission fixes dismiss the original finding after a successful fix or after confirming its unsafe permission is already gone. A confirmation alone does not report a permission change.

These limits use the existing enabled, quarantine_files and clean_htaccess opt-ins. Observe mode still forbids automatic changes. dry_run continues to control IP blocking and web-exposed-file virtual patches; it does not preview file quarantine or cleaning. Other response families have their own controls.

Files written back after removal

When CSM quarantines or cleans a file, it clears the alert state it kept for that file. If a detection finds the file there again, the finding is reported as new instead of being held back as a repeat. Dismissals remain in effect.

CSM also remembers, for seven days, the content each quarantine or clean took away. A process that writes the same bytes back to the same path raises removed_file_restored_realtime (Critical). With quarantine_files on, CSM then does what it did before: it quarantines the file again, or cleans it again. The daemon keeps this memory across restarts. A file cleaned with csm clean from the command line is not remembered. A restore from the web UI quarantine page, CSM’s own writes and official WordPress release files are never treated as the file coming back.

The saved history is read only from a private file the daemon owns. A damaged or unsafe one is logged and ignored, and detection carries on without it.

Before repeating the response, CSM checks that the file still holds the removed bytes, so a later replacement or a restore from the web UI is never removed. Removed files are watched whatever their extension. A restored .htaccess is cleaned only when clean_htaccess is on.

With kill_processes on, CSM also stops the process that wrote the file back, together with its parent processes of the same account, parents first, so a loop cannot start another writer. It does so only when those processes trace back to the web server or run detached under init, the shape of a loop a webshell leaves behind. A PHP worker that serves the site is not stopped unless it wrote the file itself. A process with a terminal, or one started from an SSH, cPanel or cron session, is left running and the file is still handled; root processes are never stopped. An SSH, cron or cPanel session anywhere above a PHP worker also prevents the kill, and so does any part of the ancestry CSM cannot read. The processes are named when the write is seen, and each is checked again through a kernel process handle just before the signal, as described above.

Restoring quarantined files

Regular-file quarantine and pre-clean backups write and sync the private content copy, metadata, and directory entries before removing or changing the original. Directory quarantine syncs the tree and metadata before moving it on the same filesystem. A directory move across filesystems is refused and leaves the source in place. Storage failures do not count as successful remediation.

New quarantine and pre-clean sidecars record the original modification time, owner, group, permissions, and size. Restore reapplies the saved attributes to the opened destination before syncing it. Linux preserves modification times at the precision supported by the destination filesystem. An ownership or timestamp failure keeps the recovery evidence and reports an error.

On Linux, restore can verify the destination after saved permissions remove all read access. The restored file keeps those permissions, including a mode with no access granted to anyone.

Older sidecars may use quarantine_at; listing and restore also read that historical spelling. Entries without a saved quarantine date sort last. Older entries have no recorded original modification time, so restore leaves the new file’s modification time in place instead of treating the archive’s timestamp as the original. Some older access-file cleanup backups also lack trustworthy ownership and permission data; check those attributes when restoring them.

Configured account roots participate in manual remediation and restore. Set up service write access for roots outside the packaged grants before enabling these operations.

Web UI restore refuses symbolic links in destination directories and does not replace an existing file or directory. If a destination changes during restore, CSM reports a conflict and retains the quarantine entry. Check the original location before retrying; a failed or interrupted file restore can leave a partial file in the directory that was opened for restoration. CSM keeps this file because removing it could discard a concurrent replacement.

Restore syncs the replacement and its containing directory before deleting quarantine evidence. A failure after a move or unlink reports partial completion and retains recovery metadata where possible. Inspect both the original and quarantine locations named in the error before retrying; a copy may already be restored while quarantine cleanup remains incomplete. These guarantees depend on the filesystem and storage device honoring sync requests.

Virtual-patch rollback uses the same directory confinement. It replaces or removes the access file only when the saved content, owner, and permissions still match, preserving later customer edits.

Virtual-patch backups are reused only when their content and saved attributes, including modification time, match. A later edit with identical bytes but a new modification time gets a separate recovery point.

Rollback isolates displaced entries in a private directory. If another writer changes the destination, CSM preserves the live replacement and reports any retained recovery directory in the error. Check that directory beneath the original destination or quarantine location before retrying. If another writer moves a restored directory, CSM cannot recover it from its old name and will not substitute a different entry into quarantine.

Configuration

auto_response:
  enabled: true
  kill_processes: true
  quarantine_files: true
  max_file_actions_per_hour: 50
  max_file_actions_per_account_per_hour: 10
  max_file_action_failures_per_hour: 3
  block_ips: true
  block_expiry: "24h"         # positive temp block duration; omitted defaults to 24h
  # max_blocks_per_hour omitted: 50 scan blocks an hour, admission ceiling 2000
  netblock: true              # enable subnet blocking
  netblock_threshold: 3       # IPs from same IPv4 /24 or IPv6 /64 before subnet block; minimum 2
  netblock_window: "168h"     # blocked IPs count this far back, expired blocks included; omitted defaults to 168h
  permblock: true             # promote temp blocks to permanent
  permblock_count: 4          # temp blocks before promotion; minimum 2
  permblock_interval: "24h"   # positive counting window; omitted defaults to 24h

  # Response to http_scanner_profile findings: "challenge" (default)
  # routes the IP to the PoW challenge when challenge.enabled is true,
  # falling through to a firewall block when it is not; "block" always
  # hard-blocks without offering a challenge.
  http_scanner_action: "challenge"

  # Deny HTTP access to confirmed exposed files with reversible .htaccess
  # rules. off: alert only; manual: `csm virtual-patch --apply`; auto:
  # apply confirmed findings except warning-only sample SQL when dry_run is false.
  virtual_patch_exposed_files: "off"

  # SAFETY DEFAULT: dry_run defaults to TRUE when this key is absent.
  # Automatic IP blocks do not touch nftables. Admission keeps bounded
  # examples of successful capacity predictions, not every attempted block.
  # Manual operator commands (`csm firewall ...`) bypass dry-run and apply.
  # Flip to false only after verifying the policy in dry-run.
  dry_run: true

  # Advisory verdict callback. CSM POSTs each impending auto-block
  # to the panel before applying. The panel can downgrade to "allow"
  # (audit-only), attach `tenant_id` for downstream correlation, or
  # add a reason. CSM fails open on hook errors. Wire contract:
  # verdict-callback-contract.md in this book.
  verdict_callback:
    enabled: false
    url: ""                            # POST target
    hmac_secret: ""                    # signing secret, or use hmac_secret_env
    hmac_secret_env: ""
    allow_unsigned: false              # true only for staged unsigned rollouts
    require_response_signature: true   # reject unsigned callback replies
    timeout_sec: 2

  # PHP-relay auto-freeze (cPanel only). Off by default; opt in
  # explicitly. dry_run defaults to true even when freeze=true so an
  # operator who enables freeze without thinking gets a dry-run.
  php_relay:
    freeze: true                       # enable the exim -Mf hook
    dry_run: true                      # safe default; flip with `csm phprelay dry-run off`
    max_actions_per_minute: 60         # rolling 60s window cap on exim -Mf invocations

Exposed-file virtual patches

Each applied deny keeps a rollback copy under /opt/csm/quarantine/pre_clean/. Re-applying the same rollback state reuses that copy; content, ownership, permissions, or remove-versus-replace changes keep separate restore points.

All-in-One WP Migration rewrites the access file inside wp-content/ai1wm-backups, so CSM also denies only .wpress filenames from the parent wp-content access file. It does not add parent-wide .zip or .gz rules because those extensions can be legitimate downloads elsewhere under wp-content.

Dry-run safety default

auto_response.dry_run defaults to true when the key is absent. This is deliberate: an operator who turns on block_ips: true without reviewing policy keeps automatic IP blocks unapplied while evaluating policy. The retained-example count surfaces in csm status --json and /api/v1/status; forecast status reports capacity decisions separately. On entry into live mode CSM requests a purge; owner-managed purges run in bounded passes and report stale examples until complete. While dry-run remains enabled, records older than a week age out.

With the firewall on and outside observe mode, admission also forecasts each automatic IP block in dry run: whether it would fit the hourly ceiling and the temporary block set, behind the blocks and forecasts before it. Status, csm doctor and findings history show the forecast, with at most one summary a minute. Admission owns new examples, pruning and purge. On a live start, existing examples also wait for its bounded purge, including while admission startup retries. New examples describe committed capacity predictions; the count also includes retained older examples until pruning or purge. It is not unique IPs or active predicted occupancy. Example loss and incomplete comparisons appear in status. A forecast is not a block; restart or re-entry into dry run starts a new session without restoring hypothetical leases from examples. The forecast fills the temporary block set as automatic admission will: of the slots operator, unknown and subnet blocks leave, a fifth is kept for direct or corroborated attacks, and an unlimited set is modelled as 10000 entries. Forecasts and previews cap each new automatic lifetime, including challenges, at auto_response.block_expiry: longer requests are cut and shorter ones stay short. Retries keep their first absolute expiry, even after a lower cap is configured; existing blocking keeps its own lifetimes. In a full set a forecast block may take the place of a lower-priority one, as live admission would: an earlier forecast block of a lower class or severity, or a legacy automatic block that recorded its origin. A new attack may also rotate out an earlier forecast block of the same class and severity once that block has held its slot for 30 minutes, within the share of the set its scope may use; an address whose forecast block was replaced or rotated out cannot rotate again before that block’s expiry. A forecast block for an address that returns after the forecast replaced its earlier block lasts only until that earlier block would have ended. A return with too little time left for a firewall block is refused without a forecast charge or retained example.

Admission checks how each finding’s address was read against its producer’s declared address sources and the check’s current policy, when it mints evidence and whenever retained evidence is used. A producer without a trusted address source cannot mint evidence. This excludes PHP relay findings, whose client address comes from a mail header a local account can forge. With auto_response.dry_run: true, these findings cannot produce a successful admission forecast. Stored evidence keeps its existing format and identifiers.

Scheduled cPanel, ModSecurity audit, per-site and central access log scans can supply automatic response forecasts from complete records with a verified address source and server time. The scheduled command-and-control connection scan can too, for established IPv4 connections this server opened. It names each one by its socket during the current boot, keeps its first-seen time across restarts when the state save completed, and reports both endpoints and the socket owner. Listener changes and overlapping scans do not refresh a matched socket’s first-seen time. Socket inodes can be reused between scans; those reports retain the earlier time, and lost first-seen state can make a forecast conflict with retained evidence. A connection on a local port that also listens still alerts but supplies no forecast, because the socket table does not show which side connected. Connections still waiting for a reply and those in the IPv6 socket table are not reported. Without a socket identity the alert still shows but supplies no forecast. Blocking the address drops its replies but does not stop data this server sends to it. Rereading a record does not refresh its time or add independent evidence. Unfinished or ambiguous records cannot supply a new observation. HTTP findings whose counts or bot-majority decisions use forwarded addresses, including mixed direct and forwarded traffic, name a client behind a trusted proxy and are refused as unreachable. The client is the first untrusted address reached from the right of the forwarded header. Periodic scans retain a bounded suffix of complete address tokens; padding to the left of a retained client does not suppress its count. A missing or unreadable right end, or a retained suffix containing only trusted proxies, names no client and is not counted. The resolver refuses a header over 4 KiB or a walk that must read more than 32 hops, its client included; hops left of the client never count. An address in web_server.trusted_proxies or challenge.trusted_proxies is never read as the client, including when its header is not trusted because it belongs to this host or the host’s addresses cannot be read; an address of this host is never trusted as a proxy. An HTTP, cPanel or IP reputation finding whose address is a known CDN or website-firewall edge, from the Cloudflare, QUIC.cloud and Sucuri ranges CSM ships (a replacement http_proxy_ranges.yaml does not change them) or, when the ASN database names it, a network in thresholds.http_asn_crawl_reverse_proxy_asns, is refused as proxy_peer, whether or not cloudflare.enabled is set. This edge refusal does not apply to SSH, FTP or mail session peers. When Apache (RemoteIPHeader, RemoteIPProxyProtocol On, a loaded or configured mod_cloudflare including DenyAllButCloudFlare, or mod_rpaf with RPAF_Enable On or RPAFenable On), nginx (set_real_ip_from) or LiteSpeed (Use Client IP in Header, in its own configuration or, on cPanel, the Apache configuration it loads) replaces the logged client address, or CSM cannot read those files completely, new HTTP findings are refused as rewritten_log and access-log lines are not IP reputation sightings; cPanel access lines still are, even when the same address also appears in a rewritten web log. An Apache, nginx or LiteSpeed access log format that writes request data into the first client token counts the same way. Leading whitespace and extra spaces after cPanel’s splitlogs virtual-host field cannot hide that token. A leading quote, brace or other non-address character guards normally escaped output. Brackets cannot guard a request value because scheduled scans accept bracketed IPv6 peers, including peers with ports. Apache format nicknames ignore case, including the TransferLog default. A definition in another virtual host or an unrelated conditional section cannot hide a log’s inline or common-format fallback. With HostnameLookups On in any scope, %h counts as a request value, because it then logs the client’s unverified reverse DNS name. Inside a mod_macro <Macro>, a parameter in a log format, format name, piped log target, module name or directive name leaves the state unknown, including a parameter that spells ServerName. Quoted macro names and parameters retain their boundaries. A parameter later in a log file path or in a server name is harmless. A parameter or ${...} variable that starts a log target leaves the state unknown, except Debian’s ${APACHE_LOG_DIR}/. That exception does not apply when Define or UnDefine can change the variable, including inside a macro. The built-in CLF nickname is also checked after piped logging removes its leading field. An ErrorLogFormat request value before an unconditional message in any output record also counts. A message that shares its field with another placeholder cannot guard later request values because that field may disappear. Unresolved Apache configuration variables in log formats, format names and server names are unknown, and so are those that could make or hide a piped log target. Unsupported format handlers, blank Apache server names and custom time formats that can write a line break are unknown, and so are unproven time formats or process, port and duration arguments in or before the field CSM reads. Empty logging conditions, including whitespace-only expressions, are unknown; a nonempty expr= condition does not change how its format is read. LiteSpeed formats with unsupported escapes, modifiers, handlers or ambiguous brace arguments are unknown, in both native XML and cPanel Apache configuration. A valid format no CustomLog, GlobalLog, TransferLog or nginx access_log uses does not count. nginx checks HTTP and stream format namespaces separately. A log selects the first previously declared format with the same name, ignoring ASCII case. Later case variants do not count as used formats. Unresolved names and malformed log declarations leave the state unknown. Entries inside maps are values, including entries read from included files. With escape=none, any request variable can introduce another log record, even after the normal client field or a quote. Binary address variables have unknown output framing. Empty server-name, hostname and port fields cannot hide a following request value. User-defined variables do not inherit trust from a built-in-looking name. nginx original-peer variable names and stream server names remain unproven because their availability depends on the installed modules and version; captures or scripts can supply request values under those names. This conservative check also applies when those variables come from nginx itself. Stream byte counts, session duration and transport protocol remain server values in the stream namespace. This build does not read a separate original-peer log field. CSM reads the files when admission starts, at the start of every reload attempt and web UI settings save, and every 10 minutes. Settings saves refresh this state before applying changes, including saves that fail or require a restart. web_server.config_dir selects the Apache or nginx root, including the Apache tree used by cPanel LiteSpeed; LiteSpeed XML remains at its standard location. The main file is apache2.conf on Debian Apache, conf/httpd.conf on RHEL or cPanel, and nginx.conf on nginx; a cPanel root ending in conf already names that directory. An absent selected Apache main file is unknown, even if a default tree exists elsewhere. A disabled or merely loaded mod_rpaf does not count as a rewrite. Malformed legacy-module arguments leave the state unknown. Cloudflare trusted-proxy hostnames or variables also leave it unknown when CSM cannot establish another active rewrite, because only Apache can resolve those values. Apache section suffixes are ignored only where Apache accepts them. Malformed closing tags and comments on closing tags for read-time conditions such as IfModule leave the state unknown; a rewrite directive found beside a parsing gap still counts as active. Files on disk can differ from what the web server loaded until it reloads, a setting in any virtual host applies to the whole host, and responses already queued are not checked again. SMTP password sprays read from Postfix mail logs can now supply forecast evidence. ModSecurity observations expire with the denial’s recent-log window. The startup Exim history scan names the newest counted send of the account it reports, using Exim’s full timestamp and zone, as the realtime mail log reader names that line. An invalid zone supplies no observation. At its event cap, the realtime cloud relay window keeps the current send’s address. An IP reputation finding supplies a forecast only with a local sighting: a record its log’s parser read the address from, dated by the server within the last 24 hours. An HTTP or cPanel sighting never uses an address listed in web_server.trusted_proxies or challenge.trusted_proxies. Admission still applies its normal evidence freshness check. The existing auto_response.dry_run setting decides whether admission forecasts these blocks or applies them.

A reader that starts inside an unfinished line still delivers its remainder to existing checks, but that fragment cannot supply admission evidence. Complete records that follow it keep their shared references.

Admission also binds each response target to its evidence. Only the mail subnet and ASN crawl entries may widen an attributed address to a containing prefix. Direct queue requests, retained candidates and reservations repeat this check, so previously queued responses cannot bypass it.

This setting is not a universal simulation mode. It gates automatic firewall and related network enforcement paths plus web-exposed-file virtual patches. File quarantine, cleanup, permission changes, and process termination are controlled by their individual auto_response flags. Leave those flags off while evaluating block policy.

IP auto-blocking still requires firewall.enabled: true. The firewall engine owns live nftables mutations and the dry-run gate; with the firewall disabled there is no engine to call, so csm validate warns on auto_response.enabled: true plus block_ips: true.

Verify dry-run state explicitly:

csm status --json | jq '.severities, .blocklist_size'
csm firewall status   # "Recently Blocked" entries with timestamps after the restart confirm live mode

To go live: set dry_run: false, then run systemctl reload csm. The field is hot-reload-safe, and a successful reload validates the config and re-records its hash. For a planned restart instead, run csm rehash once before restarting.

Verdict callback (advisory)

When verdict_callback.enabled: true, every auto-block call POSTs a signed JSON request to the panel before mutating nftables. CSM refuses to start without hmac_secret or a non-empty hmac_secret_env value unless allow_unsigned: true is set for a staged unsigned rollout. Without that opt-in, an unsigned allow response is rejected and the default block continues. When a secret is configured, CSM also requires the panel to sign the response body unless require_response_signature: false is set for a staged rollout. With that opt-out, CSM still checks any echoed nonce or timestamp when a secret is configured; a legacy response that omits both keeps working. The panel can return {"verdict": "block"} (apply), {"verdict": "allow"} (audit-only; CSM logs the decision and skips nftables), or attach metadata (tenant_id, note). The callback runs after local validation and infra-IP safety checks, and before the dry-run gate, so panels can observe dry-run decisions too. In dry run with the firewall on outside observe mode, admission also asks for each locally eligible block attempt, with CSM auto-block: <check> as the reason, up to four requests at a time, and uses the configured allow_unsigned and require_response_signature settings. A full set still allows a request when a lower-priority automatic block could be replaced or an equal-priority forecast block rotated out. Pending requests take no slots or replacement claims; admission checks capacity again after each answer, so competing requests cannot reuse one victim. An allow ends that forecast without a block. Until admission decides blocks, a panel can receive an additional request for the same automatic block. Local refusals, existing effects, capacity waits, coalescing and retries mean request counts need not be two per block. The v1 request has no dry-run field. Forecast examples and summaries are bounded, unsupported promotions are not simulated, and reload discards old policy answers.

CSM fails open on hook errors (timeout, non-2xx, malformed body): local admission continues, still subject to dry-run and capacity checks. An error proves neither a block nor a forecast example. The failure is written to the daemon log. Full request/response schema: Verdict callback contract.

Infrastructure IP DNS guard

Hostnames listed in top-level infra_ips or firewall.infra_ips are resolved every 5 minutes and their current addresses feed the infra auto-block guard. If a hostname stops resolving, the daemon emits an infra_ips_unresolvable Warning finding and keeps the last known addresses protected during the grace period (default 10 min). The finding auto-clears when resolution recovers.

Findings that always trigger IP block

When auto_response.block_ips: true and the firewall is enabled, qualifying findings in this list block the source IP. Per-row severity and challenge exceptions apply. The dry-run gate still applies if dry_run: true. Suppression rules do not stop these blocks; allowlist an address to exempt it.

Suppression rules also leave incident auto-blocking, credential-spray containment and central threat responses active. With database response enabled, suppression stops database cleanup and session revocation; the notice listing the session addresses is still sent. Suppress the action’s own check type to mute its notification; this does not disable enforcement.

Incidents and central threat responses receive new findings, including suppressed findings and checks that do not notify operators. Duplicate observations within a batch count once. Cross-account correlation uses only unsuppressed sources, and its derived alerts can be muted with their own suppression rules without removing them from enforcement.

FindingDescription
wp_login_bruteforceWordPress login flood via wp-login.php
xmlrpc_abuseXML-RPC endpoint flood
email_php_form_relayClient that made hosted sites mail many outside addresses through their forms (responses require email_protection.php_relay.ip_recipient_mode: enforce, including retries; routed to the PoW challenge first when challenge is enabled)
http_request_floodPer-IP HTTP request volume exceeds threshold (disabled by default; enable by setting thresholds.http_flood_threshold > 0)
http_scanner_profileRandom-URL probe pattern from one source IP (disabled by default; enable by setting thresholds.http_scanner_min_requests > 0; routed to the PoW challenge first unless auto_response.http_scanner_action: "block")
http_claimed_bot_unverifiedHigh-volume claimed crawler traffic while reverse-DNS verification is pending (routed to the PoW challenge first when challenge is enabled)
http_ua_spoofIP exceeding the UA anomaly threshold, including confirmed search-engine bot UA spoofing (periodic; see configuration.md for opt-in flags)
ftp_bruteforceFTP authentication flood
smtp_bruteforceSMTP authentication flood
smtp_probe_abuseRaw SMTP connect-rate flood before AUTH
mail_bruteforceIMAP/POP3/ManageSieve authentication flood without matching successful mailbox activity
mail_account_compromisedSuccessful login from an IP that repeatedly failed auth on the same mailbox, or a mail login after failures on two or more mailboxes including another one, or on a missing one. Only Critical findings block; High advisories are visibility only
admin_panel_bruteforcephpMyAdmin or Joomla admin POST flood
ssh_login_unknown_ipSSH login from an IP with no prior history, whether the realtime watcher or the periodic scan saw it first
c2_connectionOutbound connection to a known C2 server
ip_reputationIP flagged by AbuseIPDB / rspamd / upstream threat-intel
modsec_block_escalationModSecurity deny escalation
modsec_csm_block_escalationCSM-internal ModSecurity deny escalation
waf_attack_blockedWAF high-volume attacker
email_compromised_accountEmail account compromise indicator
email_cloud_relay_abuseCloud relay abuse

Successful cPanel, FTP, webmail and PAM login audit events and authenticated File Manager writes do not trigger direct blocks or challenges. Incidents containing only these audit events cannot request a block, even when they retain a higher severity from an older version. Independent attack evidence can still justify a response.

block_cpanel_logins gates cPanel multi-IP logins, API authentication failures, webmail brute force and realtime FTP authentication failures. This includes webmail challenge routing, since an unanswered challenge can become a block.

Queued block candidates are checked against the current check policy and login-blocking setting before retrying. Legacy queue entries without a check identity are discarded on upgrade; new eligible findings can queue them again. Existing firewall blocks and permanent evidence are not removed by this change.

Distributed HTTP flood rollups do not trigger a direct IP block because they describe one targeted vhost, not one source IP. The per-IP findings that feed the rollup still drive normal block decisions.

http_asn_crawl is also handled separately because one finding can carry several offending CIDRs rather than one source IP. Only Critical findings with confirmed PHP worker saturation can tempban those CIDRs, using auto_response.http_asn_crawl_tempban. Dry-run and subnet safety guards still apply.

mail_bruteforce_suspected and the High forms of mail_account_compromised are visibility only. They do not feed direct, incident, or spray auto-blocking. A separate blockable finding can still block the same source. mail_bruteforce_suspected also reports SMTP, IMAP and POP password sprays while spray detection runs in observe mode.

In enforce mode a spray block lasts thresholds.mail_spray_block_expiry (30 days by default) instead of block_expiry; an address already blocked keeps its current expiry. A block that mixes a spray finding with another finding for the address, such as a WAF or per-IP brute force finding, is a normal block: it lasts block_expiry and uses the scan budget. When the temporary block limit is full, the spray block that ends soonest is evicted first, and an operator’s temporary block is never evicted for an automatic one. A blocked address is remembered until one spray memory window after its block ends. One failed login from it in that time, on any mailbox, blocks it again for the spray length. That includes a failure logged just before an authentication outage is detected. On a shared IPv6 /64, an address blocked on the /64’s shared evidence keeps its own re-block until it is released too. An operator unblock, or an undo that removes a block, clears the address’s spray history: its re-block and the failure history of the address, or for IPv6 of its /64. An allow or temporary allow clears it even when the address holds no block, and so does the allow CSM adds for an address that a dyndns_hosts or infra_ips hostname resolves to. Its SMTP, IMAP and POP failure counts restart across all address spellings. Login trust and cracked-password records stay. Pending SMTP rejections are discarded so delayed replies cannot restore old spray evidence. A self-service unban through the panel API with an unban-scope token lifts the block and its re-block but keeps the failure history and counts, so renewed spraying is blocked again on the usual rules. An admin token or browser session on that route performs a full operator release. Failed firewall releases return an error without clearing threat state. A flush clears the spray history, per-address failure counts and pending rejections of every address. Authentication outage guards remain active after a release or flush.

Every auto-response block source - scan findings, challenge-timeout escalations, central-intel corroborated blocks, and incident spray containment - records the same evidence: a temporary threat-DB row, a blocked-IPs tracker entry, an auto_block finding visible to the block digest and alerting, and a step toward permanent-block escalation. A block the admission ledger applied is never promoted to a permanent block while it stands; its offense still counts toward a later block of the address. All of them block only while auto_response.enabled and block_ips are on; with either off, an expired challenge simply leaves the challenge list. Reloading these switches takes effect before the next block attempt, including later entries in a challenge-timeout batch. Incident block refusals caused by these switches keep the incident visible without a failed-block warning. Admission applies auto_response.max_blocks_per_hour to scan, challenge, central, and incident IP blocks. On the legacy path that budget applies to scan-driven blocks only.

Mail login spray blocks use a separate hourly budget of the same size. They reserve credit before the firewall attempt. An uncertain result keeps that credit; a confirmed non-block releases it. Retries wait when the spray budget is full, while other scan blocks keep their own budget. Waiting spray retries hold at most half of the retry queue and yield space to other retries when the queue fills. Deferred retries follow the same limits. One warning an hour names the budgets that are full when it is sent, and says when retries were dropped because the spray share of the queue was full. A failed spray reservation defers spray blocks and reports a warning, without stopping other scan blocks.

The same setting also sets the hourly ceiling of the admission ledger, which covers every IP block it executes, including challenge, central, and incident blocks. For the ledger an omitted or zero value selects 2000 and a value above 20000 is clamped to 20000; the per-IP limit above keeps reading omitted or zero as 50. An explicit value sets both. Packaged configs used to set 50, which keeps the ceiling at 50 until the key is removed; csm doctor warns about a configured ceiling below 2000. At its first start the ledger imports the current hour’s block count, so a restart cannot grant a fresh hour; a block count that cannot be read starts it without saved credit. Status and csm doctor show the ceiling and its source. A changed ceiling applies on reload, and a web UI settings save applies at the owner’s next clock tick; a failed change is retried on later ticks before admission resumes, with elapsed time credited at the saved ceiling before the new one applies. Every automatic response the existing blocking paths select is also handed to the ledger. With auto_response.dry_run false, the firewall on and outside observe mode, the ledger applies automatic IP blocks itself within this ceiling and the free slots of the temporary block set, and the existing paths leave those blocks to it. In dry run it forecasts them. With the firewall disabled or in observe mode it previews them; neither applies them. While a configured firewall engine is starting or unavailable, queued live blocks wait and new responses remain on the legacy path. Work the set has no room for waits as set_full until a slot frees: the slots operator, unknown and subnet blocks leave are divided as in the forecast, legacy automatic blocks occupy general slots, and an unlimited set counts as 10000 entries. A Critical local attack, or one with direct compromise or independently corroborated evidence, may instead take the general slot of a legacy automatic block that recorded its origin. With the firewall on, queued responses disabled by the current policy end as disabled without a withheld alert, including when their evidence expires before a restart or configuration reload. Turning a response back on requires a new eligible observation; ended work is not replayed. Status, csm doctor and findings history show the results. Forecast endings have no new per-attempt row in the action log.

The resulting auto_block findings are output evidence, not new local corroboration for central intelligence or incident correlation. They are deduplicated before the digest, attack database, history, and alert sinks receive them. Only a block that applied marks its address as auto-blocked in the attack database; a dry-run “would be blocked” warning does not.

Central intelligence and incident auto-blocking act on an address only when a finding names it as an attacker. The remote end of an outbound connection, a customer login, and advisories such as ModSecurity warnings or visitors of a mail-sending script do not count, even when another finding raised the incident’s severity. That includes a listed command-and-control server: only the C2 connection check blocks it, when auto_response.block_ips is on.

Known-customer block alert

When an automatic block applies to an address that logged in successfully as a customer in the last 30 days (cPanel, webmail, SMTP, IMAP, POP or FTP), CSM sends an alert at once: one email, and the generic alert webhook as event customer_block with the blocks under csm.customer_blocks (see the API reference). It names the address, the block reason and the check that caused it, and the customer’s login kind, account or mailbox and last login time. An IPv6 customer is named by its /64. A subnet block or netblock that covers known customers sends one message with their count and the five most recent. Every applied block counts: scan blocks, permanent promotions, challenge timeouts, central intelligence and incident blocks. A customer whose own login caused the block is left out, also when the block comes later than its cause: a mail account compromise or an FTP login after brute force names that address and account in its own Critical alert. This also applies when earlier address blocks escalate to a range block: its count and examples include only the remaining customers. Each block names the command that lifts it: csm firewall remove <ip> for an address, csm firewall remove-subnet <cidr> for a range. An allow rule (csm firewall allow <ip>) trusts the address on every port. It does not pass a blocked range, but CSM never blocks a range over an allowed address.

The alert is the false-positive check of automatic blocking, never an exemption. The block stands with its configured length, and its notice still goes to the daily summary, which also lists the block with its customers, so a failed alert still reaches you. A login with stolen credentials also makes an address known, so the alert can show the block of an attacker holding a customer’s password, which is worth seeing too. Each applied block sends at most one message; a later new block of the same address sends another. A promotion to a permanent block is named in its block’s message when both reach CSM together; a promotion that reaches CSM apart from its block sends a message of its own. The alert replaces the live watched-country alert for the same block, and the block still counts in the watched-country section of the daily summary. It does not spend the hourly alert budget, goes out with alerts.block_digest off and ignores alerts.block_digest.channel. A phpanel webhook does not receive it. Dry-run and observe-mode verdicts that would have blocked a known customer are listed in the daily summary instead.

Safety Guards

  • Never kills root processes, system daemons, or cPanel services
  • Infrastructure IPs (infra_ips and firewall.infra_ips) are never blocked or sent to the challenge page
  • A block of an address that recently logged in as a customer is alerted at once and never exempted
  • Subnet blocks refuse the default route and any range that covers infrastructure, local host, allowed, or port-specific allowed IPs
  • Quarantined files preserve full metadata for restoration
  • Every regular file is copied from its verified open descriptor into a private quarantine inode before the detected name is removed. Other hard links are reported after removal; a file swapped into the detected path is reported as a refused remediation, with the captured copy kept as evidence and the replacement left untouched
  • Realtime signature auto-quarantine requires high confidence: category webshell or dropper, file size at least 512 bytes, and either Shannon entropy >= 5.5 or hex density > 20% with an obfuscated-execution signal. This prevents legitimate WordPress plugins from being quarantined.
  • IP blocks are limited by auto_response.max_blocks_per_hour: admission defaults to 2000/hour and legacy scan blocking to 50/hour.
  • CRITICAL alerts and threat-intel reputation sightings always bypass the operator email/webhook rate limit (default 30/hour); lower-severity findings batched with them still count against it
  • Attacks CSM blocked or challenged, and its applied block and challenge notices, go to the daily summary instead of alert email and the generic webhook; an attack whose block failed, is still queued or ran in dry run is alerted immediately, as are a block of a Cloudflare-covered address and the web attacks from it
  • Trusted countries (trusted_countries) suppress login alerts from expected geolocations

What CSM Detects in Real-Time

Beyond standard malware patterns, CSM detects advanced evasion techniques:

  • Fragmented function names: attackers split base64_decode across variables ($a="base"; $b="64_decode") to evade simple string matching
  • Appended payloads: malicious code added to the end of large legitimate files, beyond typical scan windows. Realtime PHP checks scan the first and last 32KB, and periodic PHP content analysis scans a larger head window plus the tail.
  • Non-PHP backdoors: Perl, Python, Bash CGI scripts in web directories (detects toolkits like LEVIATHAN)
  • SEO spam injection: gambling/togel dofollow link injection into theme files
  • WordPress brute force: real-time access log monitoring for wp-login.php and xmlrpc.php floods (blocks within seconds, not the 10-minute periodic scan)
  • Admin-panel brute force: same access-log path, tracks POSTs to /phpmyadmin/index.php, /pma/index.php, /phpMyAdmin/index.php, and Joomla /administrator/index.php. Emits admin_panel_bruteforce and auto-blocks the IP. Path matcher is intentionally tight to avoid false positives on shared hosting; Drupal and Tomcat Manager use different attack shapes and need separate detectors.
  • SMTP brute force and probes: tails /var/log/exim_mainlog on cPanel and non-cPanel Exim hosts where the file exists. Emits smtp_probe_abuse and smtp_bruteforce (per-IP, auto-blocks), smtp_subnet_spray (per-/24, auto-blocks the whole subnet), and smtp_account_spray (per-mailbox, visibility only). Spray detection adds mail_bruteforce_suspected in observe mode and mail_account_compromised for a login after failures on other mailboxes.
  • Mail brute force: tails /var/log/maillog for direct IMAP, POP3, and ManageSieve auth failures. Composes with the existing geo-login monitor so email_suspicious_geo keeps working. Emits mail_bruteforce, mail_bruteforce_suspected, mail_subnet_spray, mail_account_spray, mail_account_compromised, and mail_auth_backend_degraded. Established good sources with a confined stale-password pattern emit the suspected advisory without auto-blocking. A compromise finding from an IP established on at least two other mailboxes stays visible as High without auto-blocking. Wider spraying and compromise without that standing still block. When the auth backend is degraded, mail_bruteforce and mail_subnet_spray auto-blocking pause until backend errors age out.
  • Mail auth backend probe (cPanel): independently of the log signals above, CSM opens the cpdoveauthd socket on a short interval. dovecot keeps answering its IMAP/POP3 ports during a cpdoveauthd outage, so cPanel’s own service checks do not notice, yet every login fails regardless of password. When the probe finds the socket unreachable CSM raises mail_auth_backend_degraded and pauses both mail and SMTP brute-force auto-block. With auto_response.mail_auth_recovery.restart_enabled, CSM restarts the mail service once the backend has been continuously down past down_grace (default 10m, rate-limited), so a brief blip during maintenance never triggers a needless restart. Changes to mail auth recovery settings require a daemon restart.

Network dry-run precedence

Three settings combine for direct-SMTP BPF enforcement. Any applicable dry-run value that is true wins; live network denial requires all three to be false.

LayerKnobDefaultEffect when true
Auto-responseauto_response.dry_runtrueRecord automatic block decisions without applying firewall denial
Detectordetection.direct_smtp_egress.dry_runtrueSuppress detector-scoped action
Kernelbpf_enforcement.dry_runtrueBPF program emits decision but allows traffic

The kernel knob is consulted by the BPF program itself; the others gate userspace action paths. All three default to true on a first install so a configuration mistake cannot start blocking traffic.