Troubleshooting & FAQ

This page gathers frequently asked questions and the checks to run when something behaves unexpectedly. In most cases, the cause is a deliberate state (simulation mode still active) or an agent that is temporarily unreachable.

In plain terms

• Most "problems" are actually expected states: a simulation mode still active, or an agent that just restarted.
• Each section below gives the check to run from the console, with no technical work on the server.
• When in doubt, the audit log (System tab) records who changed what.

The agent appears offline

Symptom: the agent connection state is red/orange in the console.

The agent regularly sends a heartbeat. The console considers it up to date if this signal is recent; beyond a delay, the agent is flagged offline and some validations (features, AppSec) are paused as a safety measure.

What to check:

1. Use the Test connection button in the System tab.
2. An agent that just restarted can take a few minutes to re-emit its heartbeat, wait for the next cycle.
3. Check that the server hosting the agent is running and reachable.
4. If the state does not return to green after several cycles, contact support.

The protection is not blocking anything

Symptom: clearly hostile traffic is not being blocked.

Most frequent cause: simulation mode is active. In simulation, decisions are logged and not applied.

What to check, in order:

1. Simulation mode: is an amber banner shown at the top of the console? If so, the protection is in observation only. Turn off simulation to switch to real enforcement.
2. Emergency disarm: has the agent been disarmed? Disarming puts the protection into monitoring only. Re-arm it from the System tab.
3. Panic mode: it submits traffic to a verification. Triggered manually. Turn it off once the incident is resolved.
4. Trusted IP: is the IP in question in the trusted list? A trusted IP bypasses the bundle’s HAProxy rules (see the false positive section below).
5. Offer tier: some protections depend on the subscribed tier. Check that the expected capability is available at your tier (Configuration reference).

A legitimate visitor is blocked (false positive)

Symptom: a customer, a provider or an internal tool is wrongly blocked.

Solution: add their IP to the trusted list. It bypasses the bundle’s HAProxy rules. For a decision already set, lift it from the console.

How to proceed:

1. Identify the IP in question, the Response tab allows search and investigation by IP.
2. Add it from the System tab (agent scope for one machine, team scope for the whole organization), with a justification comment.
3. Check the effective preview to confirm it is taken into account.

For a recurring false positive on a specific endpoint, a custom rule set to log_only lets you observe without blocking before adjusting.

A trusted IP is rejected on input

Symptom: an error message appears when adding a trusted IP.

Input is validated by a central rule. Common rejections:

• Invalid format: the value is not a valid IP or CIDR (IPv4/IPv6).
• Prefix too broad: the range exceeds the allowed floor (at least /16 in IPv4). Narrow the range.
• Duplicate: the entry already exists in the same scope.
• Cap reached: the limit depends on your tier.
• Missing comment: the justification (3 to 255 characters) is mandatory.

Operating system

Confirm your Debian version with us before installing.

The agent relies on rsyslog, installed with the package.

A custom rule "does nothing"

Symptom: a rule is created but has no visible effect.

What to check:

• Is the rule enabled? A disabled rule is not applied.
• Is the action log_only? In that case, the rule observes and logs without acting on traffic, this is the expected behavior.
• The score_boost action does not cause a direct block: it raises a score and can remain without visible effect.
• Is simulation mode active? If so, no rule is actually applied.

After a change, nothing changes on the agent side

Configuration changes (trusted IPs, rules, disarm) are applied via the signed bundle pushed down to the agent, or via an immediate synchronization trigger. A short delay is normal.

• Wait for the agent’s next synchronization cycle.
• Check the connection state: an offline agent does not receive its new configuration until it has restored contact.
• The audit log confirms that the change was properly recorded on the console side.

The agent lifecycle (install, updates, removal) follows the standard Debian package process (apt).

Where to find more help

• Protection scope and what AtriShield does not cover: Security & disclosure.
• Report a vulnerability: see the responsible disclosure policy.
• For any other blocker, contact AtriShield support.