Kernloom IQ (kliq) — Full reference

Kernloom IQ is the local Policy Decision Point (PDP). It reads telemetry from Shield, scores each source, and applies progressive enforcement through the active PEP adapter.

This page covers:

• Decision engine — how IQ reasons
• Profiles — starting configurations with real values
• Graph Learner — Zero Trust path enforcement
• Autotune — self-tuning baseline
• Exemptions — whitelist and feedback
• CLI flag reference — every argument

Decision engine

Per-tick inputs

Every tick (--interval, default 1s), IQ reads per-source deltas from Shield’s telemetry maps:

• PPS — packets per second
• SYN/s — TCP SYN packets per second
• scan/s — distinct destination ports contacted per second (port-scan signal)
• DropRL/s — packets dropped by Shield’s rate limiter per second

Severity score

Each signal is normalised by a trigger threshold and capped:

nPPS  = min(PPS   / trig-pps,  sev-cap)
nSYN  = min(SYN/s / trig-syn,  sev-cap)
nSCAN = min(scan/s/ trig-scan, sev-cap)

severity = w-pps × nPPS + w-syn × nSYN + w-scan × nSCAN

Strikes → levels

Severity is converted to strikes using step thresholds (--sev-step*, --sev-delta*). Strike counts are mapped to enforcement levels:

Hysteresis

IQ prevents rapid oscillation using:

• --up-need / --down-need — consecutive high/low ticks required to change level
• --min-hold-soft / --min-hold-hard — minimum time in each level
• --cooldown — minimum time between any level changes

Non-compliance escalation

If a source is in RATE_HARD and continues producing DropRL/s (it is hitting the limiter and not backing off), IQ accelerates escalation to BLOCK. Controlled by --noncomp-at, --noncomp-drop, --noncomp-sev.

Block gate

Blocking behind NAT is risky (one bad source can block many legitimate users). Gate it:

--block-min-sev 3.0     # only block if severity >= 3.0 ...
--block-min-dur 60s     # ... for at least 60 seconds

If the gate fails, IQ stays at HARD instead of BLOCK.

Configuration

IQ has two independent configuration axes in v0.2.0.

PDPConfig (--pdp-config) — what to measure

A PDPConfig YAML file is the primary configuration mechanism. It controls signal engine thresholds, the autotune schedule, progressive enforcement parameters, and adapter parameters. It replaces the older --profile flag for most use cases.

--profile still works as a shorthand but the PDPConfig approach is recommended — it is Forge-compatible and gives full control over the bootstrap schedule.

16 PDPConfig files ship in configs/pdp/ (8 bootstrap + 8 production):

Public-facing profiles (ziti-controller, ziti-router, web-server, reverse-proxy) have graph.enabled: false — graph learning is not useful when clients are unknown internet IPs and the flow map fills up immediately. Internal profiles (idp, database, api-server, nas) have graph.enabled: true.

Bootstrap profiles start with blocking disabled (block-at=999) and use max_down: 0.10 (10%/hour) so thresholds converge from the cold-start value within 48h. Switch to the production profile once you have observed stable operation.

Feature profile (--feature-profile) — which subsystems are active

A feature profile controls which IQ subsystems run. It is auto-derived from the --graph flag when not set explicitly:

Check which subsystems are active at runtime:

kliq runtime status graph-learning
kliq runtime status klshield-light   # → explains no kliq needed

Legacy profile values

For reference: the older --profile flag seeds these initial values (all adapted by autotune):

SoftRate and HardRate are in packets per second. BlockAt=999 means blocking is effectively disabled.

Recommended rollout

1. Copy the right PDPConfig for your node to /opt/kernloom/attested/etc/pdp/node.yaml
2. Start with --dry-run=true and --whitelist-learn=true
3. Let IQ observe and autotune on real traffic for 7–14 days
4. Review state transitions; add whitelist entries for known-good sources
5. Enable enforcement: --dry-run=false

Graph Learner

The Graph Learner is an optional module that builds a baseline of observed communication paths and can enforce Zero Trust once the baseline is frozen.

Enable with --graph. Control the mode with --graph-mode.

Modes

Edge lifecycle

candidate  →  learned  →  frozen
                 │
              approved (manual)
              denied   (manual, never overwritten)

Suspicious sources (currently RATE_SOFT, RATE_HARD, or BLOCK) are automatically excluded from the baseline to prevent polluting it with attack traffic.

Workflow

Step 1 — learn your baseline:

sudo /opt/kernloom/attested/kliq \
  --pdp-config=/opt/kernloom/attested/etc/pdp/idp-bootstrap.yaml \
  --graph --graph-mode=learn \
  --dry-run=true --whitelist-learn=true

Run for several days to a week to capture representative traffic patterns.

Step 2 — review and clean up:

kliq graph export                       # export all edges
kliq graph export --sort=state          # grouped by state
kliq graph edges --sort=state           # overview with state counts
kliq graph baselines --sort=obs         # per-edge EWMA stats (PPS/BPS peaks)
kliq graph approve-ip <ip>              # mark an edge as explicitly approved
kliq graph deny-ip <ip>                 # mark an edge as denied

Step 3 — check readiness before freezing:

kliq graph freeze --dry-run

Reports how many edges would be frozen, how many candidates are still immature, how many low-confidence edges exist. Does not write anything.

Step 4 — freeze the baseline:

kliq graph freeze

This locks all learned edges to frozen. New traffic after this point will be compared against the baseline.

Step 5 — observe before enforcing:

sudo /opt/kernloom/attested/kliq --graph --graph-mode=frozen-observe

Run for a few days. Watch for unexpected signals (legitimate sources you forgot to include). Add them with approve-ip if needed.

Step 6 — full enforcement:

sudo /opt/kernloom/attested/kliq --graph --graph-mode=frozen-enforce

Any source taking a path not in the frozen baseline is immediately forced to BLOCK.

Independence from behaviour-based enforcement

The graph enforces path-based Zero Trust only. A source with a known, frozen edge is still fully subject to IQ’s severity scoring.

If a known node starts sending a SYN flood, scanning ports, or generating unusual packet volume, progressive enforcement applies normally — the graph has no say in this. IQ asks “is this behaviour acceptable?” independently of whether the graph knows the path.

This matters in practice: a compromised workload may deliberately stay on known communication paths to avoid triggering the graph, but its traffic patterns will still be anomalous to IQ. The two mechanisms catch different things and neither exempts a source from the other.

The only exception is the IQ whitelist (--whitelist): sources explicitly whitelisted in IQ are exempt from all enforcement. Graph approval is not the same as an IQ whitelist entry — they are separate and independent.

Storage

The graph is stored in a unified SQLite database (kliq.db, default path: /var/lib/kernloom/iq/kliq.db). Since v0.2.0 this database also contains source baseline data and edge baseline EWMA stats in separate tables. It persists across restarts independently of state.json.

New in v0.2.0: learning improvements

Source baseline

Active when feature-profile ≥ iq-learning. IQ tracks per-source IP EWMA statistics separately. A known high-traffic source gets an effective trigger of max(global_trigger, source_peak × 1.2), so a source that normally sends 250 PPS does not trip a global trigger of 100 PPS. Unknown sources fall back to the global trigger.

Edge baseline improvements

• Two-phase EWMA alpha: bootstrap alpha=0.10 while observations < 30, stable alpha=0.02 after. The baseline converges quickly but resists being moved by short spikes.
• Decaying peak (peak_decay_half_life): a single historical spike no longer permanently defines the ceiling. A peak from 14 days ago is worth 50% of its original value (peak_decay_half_life: "336h").

Anti-poisoning (three layers)

Three layers prevent attacks from corrupting baselines:

1. TrigPPS cap — observations above the host-level trigger are never written
2. SuspiciousRegistry — source AND edge-level suspicious state tracked separately; a freeze violation on one edge no longer blocks learning for all edges from that source
3. 30s pending buffer — baseline updates are delayed 30s and dropped if the source or edge was flagged in that window

kliq graph baselines

kliq graph baselines [--all] [--sort=obs|state|src|port|pps|bps]
kliq graph baselines reset

Shows per-edge EWMA stats including PPS_PEAK and BPS_PEAK columns.

Autotune

IQ can learn your trigger thresholds (trig-pps, trig-syn, trig-scan) from observed traffic using Median + MAD statistics.

Learning only happens on clean ticks — ticks where:

• the fraction of high-severity sources is below --learn-frac-gt
• no source is in BLOCK (if --learn-skip-if-blocks=true)
• global drop ratio is below --learn-max-drop-ratio

This prevents attack traffic from poisoning the baseline.

Bootstrap schedule

The bootstrap schedule runs autotune more aggressively for the first ~14 days, then slows down to a steady-state interval. It has three phases with decreasing update rates and increasing conservatism.

State is saved to /var/lib/kernloom/iq/state.json and reloaded on restart, so the schedule survives process restarts.

Bug fix (v0.2.0): Versions before v0.2.0 had a bug where the autotune could get stuck on quiet nodes and never apply updates (the timer reset on every skip, creating a permanent loop). This is fixed in v0.2.0. Additionally, bootstrap phase 1 previously used max_down: 0.02 (2%/hour), meaning triggers could take 70+ hours to converge from the cold-start value. The new PDPConfig profiles use max_down: 0.10 (10%/hour) so convergence happens within 48h.

Troubleshooting: If autotune triggers are not moving after 2–3 revisions, delete /var/lib/kernloom/iq/state.json and restart IQ.

Exemptions

Whitelist (permanent)

Sources in the whitelist are never scored, never enforced. Add IPs, IPv6 addresses, or CIDRs — one per line:

# /opt/kernloom/attested/etc/whitelist.txt
203.0.113.7
203.0.113.0/24
2001:db8::1

Reloaded automatically every --whitelist-reload (default 10s).

Feedback (temporary)

Use feedback for time-bound exemptions without permanently whitelisting:

[
  {"target":"203.0.113.7","action":"forgive","ttl":"24h","notes":"partner NAT"},
  {"target":"198.51.100.0/24","action":"whitelist","until":"2026-06-01T00:00:00Z"}
]

Reloaded every --feedback-reload (default 10s). Prefer until over ttl for stable expiry across restarts.

CLI flag reference

Core runtime

Profile and persistence

Graph Learner

Whitelist

Feedback

Bootstrap

Autotune

Clean tick gates (anti-poison)

Severity model

Strike mapping

Level thresholds

Enforcement actions

Block gate

Hysteresis

Non-compliance escalation

Housekeeping

See also