Configuration Reference
Every setting lives in /opt/coredetection/config.ini, organized into sections. Edit the file and restart the service, or change most settings live through the REST API. This page documents every section and key.
[section] exactly as they appear in the file. Defaults shown are the shipped values; (empty) means no value, — means optional / no default.Two kinds of logging
CoreDetection keeps two separate, unrelated logs. They are easy to confuse, so here is the distinction:
log_outputs ([general]) | [attack_log] | |
|---|---|---|
| Purpose | Live operational / console logging for monitoring and troubleshooting. | Permanent attack history that powers the reporting API. |
| Destination | stdout → systemd journal (journalctl -u coredetection). | A self-rotating file (attacks.jsonl). |
| Format | Human-readable text lines. | Structured JSONL (one JSON object per line). |
| Read by the API? | No. | Yes — GET /reports/attacks. |
| Rotation | Managed by journald. | Built-in (max_size_mb / max_backups). |
| Content | events (per-attack), totals (per-cycle counts), webhook (queue status). | Attack lifecycle events: START / REVIVE / END. |
In short: log_outputs controls what you see happening right now, while [attack_log] is the archive of attacks you query later for reports.
Jump to section
General [general]
Core paths and logging behavior.
| Key | Description | Default |
|---|---|---|
debug_mode | Increase log verbosity for troubleshooting. | true |
license_file | Path to the license file. | license.lic |
network_config_file | Path to the YAML file listing protected CIDR prefixes. | network.yaml |
log_outputs | Which log streams to emit: events (per-attack), totals (per-cycle counts), webhook (queue lines). | ["totals","webhook"] |
Flow Data Source [database_settings]
Connection to the time-series database CoreDetection reads enriched flow records from. The flow collector and this database are bundled and installed automatically by the CoreDetection installer — you do not set them up separately. Default values point to the bundled stack on the same server; only change them if you run the database on a different host.
| Key | Description | Default |
|---|---|---|
clickhouse_host | Database host. | localhost |
clickhouse_port | Native TCP port. | 9000 |
clickhouse_user | Username. | default |
clickhouse_password | Password. | (empty) |
clickhouse_database | Database name. | default |
connection_timeout | Connection timeout in seconds. | 30 |
Timing [timing_settings]
How often detection runs and how much history each cycle analyzes.
| Key | Description | Default |
|---|---|---|
detection_window_minutes | Sliding window of traffic analyzed each cycle. | 1 |
check_interval_seconds | How often the detector runs a cycle. | 60 |
Detection Thresholds [detection_thresholds]
Severity escalation by bandwidth and packet rate. Tune to your link size (min ≈ 0.5% of link, MEDIUM ≈ 2%, HIGH ≈ 5%, CRITICAL ≈ 20–30%).
| Key | Description | Default |
|---|---|---|
min_bandwidth_gbps | Minimum bandwidth to consider traffic an attack (Gbps). | 0.40 |
medium_bandwidth_gbps | MEDIUM severity threshold (Gbps). | 0.60 |
high_bandwidth_gbps | HIGH severity threshold (Gbps). | 1.00 |
critical_bandwidth_gbps | CRITICAL severity threshold (Gbps). | 2.50 |
syn_flood_pps | SYN flood packets/sec threshold. | 50000 |
ack_flood_pps | ACK flood packets/sec threshold. | 30000 |
rst_flood_pps | RST flood packets/sec threshold. | 10000 |
fin_flood_pps | FIN flood packets/sec threshold. | 10000 |
udp_flood_pps | UDP flood packets/sec threshold. | 50000 |
icmp_flood_pps | ICMP flood packets/sec threshold. | 15000 |
high_pps | Hard PPS ceiling that forces CRITICAL regardless of bandwidth. | 50000 |
min_sources_distributed | Minimum unique sources for a distributed attack. | 80 |
min_sources_botnet | Minimum unique sources for botnet classification. | 80 |
min_countries_global | Minimum countries to flag a global attack. | 3 |
Display & Query Limits [display_settings]
Limits for query results and console output. Higher values give smart detection more data to analyze.
| Key | Description | Default |
|---|---|---|
max_sources_display | Top source IPs kept and shown (improves clustering analysis). | 100 |
max_countries_display | Top countries kept and shown. | 30 |
max_asns_display | Top ASNs (needed for trusted-ASN detection). | 50 |
max_flows_display | Flow samples kept for pattern analysis. | 50 |
max_src_ports_display | Top source ports. | 10 |
max_dst_ports_display | Top destination ports. | 10 |
result_limit | Maximum query result rows. | 1000 |
Traffic Filters [filters]
Which traffic the detection query evaluates.
| Key | Description | Default |
|---|---|---|
dst_net_role | Destination network role to evaluate (required by the query). | customers |
in_if_boundary | Ingress interface boundary filter. Leave blank to disable. | external |
Advanced Heuristics [advanced_settings]
Fine-grained detection tuning and attack lifecycle behavior.
| Key | Description | Default |
|---|---|---|
tcp_conn_ratio_threshold | TCP connection-exhaustion ratio threshold. | 100 |
udp_distinct_ports_threshold | UDP distinct-ports threshold for targeted detection. | 5 |
icmp_avg_packet_size_threshold | ICMP average packet size for fragmentation detection. | 1400 |
attack_end_grace_cycles | Consecutive missed cycles before an attack is marked ENDED. | 8 |
ended_attack_retention_cycles | Keep ENDED attacks in memory: -1 = forever, 0 = purge now, N = N cycles. | -1 |
API Server [api_settings]
The REST API used to manage and monitor the appliance.
| Key | Description | Default |
|---|---|---|
api_enabled | Enable the REST API server. | true |
api_port | TCP port the API listens on. | 9009 |
api_key | Secret key required by all endpoints except /health. Use a long random value. | (secret) |
api_base_path | Base URL path for all endpoints. | /CoreDetection/api/v0 |
api_rate_limit | Max requests per minute per IP (0 to disable). | 100 |
Attack History Log [attack_log]
Self-rotating JSONL file that powers the built-in /reports API — no database required.
| Key | Description | Default |
|---|---|---|
enabled | Append attack lifecycle events (START / REVIVE / END) to the file. | true |
file | Path to the JSONL history file. | /var/log/coredetection/attacks.jsonl |
max_size_mb | Rotate once the active file exceeds this size in MB (0 = never). | 50 |
max_backups | Number of rotated backups to keep (attacks.jsonl.1 … .N). | 5 |
Alerting [alerts]
Local push notifications (Telegram / email) that work without the portal.
| Key | Description | Default |
|---|---|---|
enabled | Master switch for push alerts. | false |
min_severity | Minimum severity that triggers an alert: LOW | MEDIUM | HIGH | CRITICAL. | HIGH |
on_start | Notify when an attack starts. | true |
on_end | Notify when an attack ends. | true |
telegram_enabled | Enable the Telegram channel. | false |
telegram_bot_token | Bot token created via @BotFather. | (empty) |
telegram_chat_id | Numeric chat / channel id to notify. | (empty) |
email_enabled | Enable the email (SMTP) channel. | false |
smtp_host | SMTP server host. | (empty) |
smtp_port | SMTP server port. | 587 |
smtp_username | SMTP username. | (empty) |
smtp_password | SMTP password. | (empty) |
email_from | From address. | (empty) |
email_to | Comma-separated list of recipients. | (empty) |
BGP Mitigation [bgp_settings]
The built-in BGP speaker that announces blackhole / mitigation routes to your routers.
| Key | Description | Default |
|---|---|---|
enabled | Enable the built-in BGP speaker. | true |
local_asn | Local autonomous system number. | 65001 |
router_id | BGP router ID. | (server IP) |
default_mitigation_nexthop | Default next-hop for mitigation routes. | 10.10.20.1 |
announce_critical_attacks | Announce a route on CRITICAL attacks. | true |
announce_high_attacks | Announce a route on HIGH attacks. | true |
announce_medium_attacks | Announce a route on MEDIUM attacks. | false |
announce_low_attacks | Announce a route on LOW attacks. | false |
blackhole_community | BGP community attached to blackhole routes. | 65001:666 |
mitigation_community | BGP community attached to mitigation routes. | 65001:100 |
no_export_community | NO_EXPORT community. | 65535:65281 |
neighbor_N_name | Friendly name of static neighbor N (N = 1, 2, …). | Core-Router-1 |
neighbor_N_ip | Neighbor IP address. | — |
neighbor_N_asn | Neighbor ASN. | — |
neighbor_N_type | Session type: ebgp | ibgp. | ebgp |
neighbor_N_enabled | Enable this neighbor. | true |
neighbor_N_nexthop | Per-neighbor next-hop override. | — |
neighbor_N_multihop | eBGP multihop TTL. | 255 |
neighbor_N_password | Optional MD5/TCP session password. | — |
default_holdtime | BGP hold timer (seconds). | 180 |
default_keepalive | BGP keepalive timer (seconds). | 60 |
default_connect_retry | Connect-retry timer (seconds). | 120 |
enable_route_splitting | Split an announced prefix into smaller prefixes. | true |
split_prefix_lengths | Prefix lengths to split into. | 24,23,22 |
BGP FlowSpec [flowspec]
Targeted traffic filtering (RFC 5575 / RFC 8955 — same NLRI on the wire) as an alternative to a full blackhole. Matches protocol, ports, packet length, TCP flags, and fragmentation via the API. Actions: drop, rate-limit, accept (scrubbing nexthop), redirect (RT), mark (DSCP). When enabled, attack mitigation announces FlowSpec INSTEAD of a blackhole. Requires FlowSpec-capable routers (Juniper, Cisco IOS-XR, Nokia SR OS, Arista, Huawei, BIRD, etc.). Disabled by default.
| Key | Description | Default |
|---|---|---|
enabled | Enable FlowSpec mitigation. Toggling this live (via the API) automatically re-negotiates the address family with peers — no service restart required. | false |
default_action | Default action for matched traffic: drop | rate-limit | accept | redirect | mark. | drop |
rate_limit_bps | Bandwidth ceiling (bits/sec), used only when default_action = rate-limit. | 1000000000 |
IP Blocklist [blocklist]
Ingests threat-intelligence and operator-defined IP/CIDR feeds and enforces them via FlowSpec source-prefix drop (destination 0.0.0.0/0). Requires flowspec.enabled=true and blocklist.enforce=true. Feeds are declared in separate [blocklist_feed_N] sections — one section per feed. Feed files are plain text with one IP or CIDR per line; lines starting with # or ; are comments. Supported URLs: https://, http://, file:///path, or a local file path.
| Key | Description | Default |
|---|---|---|
enabled | Enable periodic feed refresh and blocklist ingestion. | false |
enforce | Push FlowSpec drop rules for each entry (requires FlowSpec enabled on peers). | true |
refresh_interval_minutes | Automatic refresh interval in minutes. | 60 |
manual_entries | Comma-separated static IP/CIDR entries merged with feeds. | (empty) |
Smart Detection [smart_detection]
The 3-layer Smart Detection engine (rhythm + fingerprint + memory) with ASN trust, baselines, and consensus scoring — reduces false positives by 50–70%.
| Key | Description | Default |
|---|---|---|
enabled | Require attacks to pass smart analysis (off = threshold-only detection). | true |
memory_size | Maximum attack signatures remembered (~150 bytes each). | 5000 |
memory_persistence | Persist attack memory to disk across restarts. | true |
Trusted ASN Analysis [trusted_asn_analysis]
Lowers attack scores for traffic from CDN / cloud ASNs to prevent false positives.
| Key | Description | Default |
|---|---|---|
enabled | Enable trusted-ASN scoring. | true |
trusted_asns | Comma-separated trusted ASN numbers (no "AS" prefix). | 13335,20940,15169,… |
high_trust_threshold | Fraction of trusted traffic for the high-trust band. | 0.80 |
high_trust_bonus | Score adjustment at high trust (negative reduces score). | -45 |
medium_trust_threshold | Fraction of trusted traffic for the medium band. | 0.50 |
medium_trust_bonus | Score adjustment at medium trust. | -15 |
low_trust_threshold | Fraction of trusted traffic for the low band. | 0.20 |
low_trust_bonus | Score adjustment at low trust. | -5 |
max_sources_per_asn | Max sources from one trusted ASN before it looks suspicious (cloud abuse). | 100 |
log_asn_details | Log the per-ASN breakdown in detection results. | true |
Trusted Destinations [trusted_destinations]
Destinations listed here are completely ignored — no alerts, webhooks, BGP, or logs.
| Key | Description | Default |
|---|---|---|
enabled | Enable destination whitelisting. | true |
trusted_subnets | CIDR subnets to ignore entirely (comma-separated). | 156.229.62.0/24 |
log_filtered | Log filtered attacks for debugging (false = silent). | false |
Smart Detection Thresholds [smart_detection_thresholds]
Tunable bands for the rhythm-analysis layer.
| Key | Description | Default |
|---|---|---|
rhythm_variance_critical / high / low / min | Traffic variance bands — higher variance is more attack-like; min flags constant-rate floods. | 1000 / 800 / 200 / 100 |
rhythm_smoothness_critical / high / low / max | Smoothness bands — lower is more jagged/attack-like; max flags constant-rate floods. | 0.3 / 0.5 / 0.7 / 0.8 |
rhythm_predictability_high / low | Predictability bands — lower is more chaotic/attack-like. | 0.3 / 0.7 |
ipv6_clustering_method | Method used to cluster IPv6 sources. | simple_subnet |
Pseudo-L7 Inference [pseudo_l7]
Infers application-layer attack types (DNS/NTP/SSDP/Memcached/HTTP/Slowloris) from L4 flow data.
| Key | Description | Default |
|---|---|---|
enabled | Enable pseudo-L7 inference. | true |
dns_amp_min_packet_size | DNS amplification: min avg packet size from UDP src port 53. | 512 |
ntp_amp_min_packet_size | NTP amplification: min avg packet size from UDP src port 123. | 468 |
ssdp_min_packet_size | SSDP amplification: min avg packet size from UDP src port 1900. | 200 |
memcached_min_packet_size | Memcached amplification: min avg packet size from UDP src port 11211. | 1400 |
http_flood_max_packet_size | HTTP flood: max avg packet size (small requests = flood). | 600 |
http_flood_min_sources | HTTP flood: minimum unique sources to infer. | 20 |
slowloris_max_pps_per_source | Slowloris: max packets/sec per source (very slow connections). | 5.0 |
amplification_min_src_port_dominance | Min fraction of traffic from a single source port (0.0–1.0). | 0.60 |
Webhook (Portal Integration) [webhook_settings]
Used to push attack data to the CoreTech portal. For standalone deployments set webhook_enabled = false.
| Key | Description | Default |
|---|---|---|
webhook_enabled | Send attack data to a webhook endpoint. | true |
webhook_url | Webhook endpoint URL. | — |
webhook_auth_header | Authentication header name. | Authorization |
webhook_auth_token | Authentication token value. | (secret) |
detector_id | Unique identifier for this detector instance. | CoreDetection |
debug_webhook_save | Save webhook payloads to disk for debugging. | false |
debug_webhook_dir | File/directory for saved payloads. | webhooks.log |
Webhook (Advanced) [webhook_advanced]
Reliability tuning for the webhook client.
| Key | Description | Default |
|---|---|---|
timeout_seconds | HTTP client timeout. | 30 |
insecure_tls | Skip TLS certificate verification (development only — dangerous). | false |
circuit_breaker_threshold | Consecutive failures before the circuit opens. | 5 |
circuit_breaker_timeout | Seconds to wait before retrying when the circuit is open. | 30 |
Security
- Keep
api_keyand any tokens secret; rotate them periodically. - The API has no built-in TLS. If exposed beyond localhost, terminate TLS at a reverse proxy (nginx / Traefik).
- Restrict the API port to trusted management hosts with a firewall.
- For standalone deployments, set
webhook_enabled = false.