firmis monitor - Runtime Monitoring

Static scans tell you what the code says. Runtime monitoring tells you what the agent actually does.

firmis monitor watches your AI agents as they run, intercepting tool calls, inspecting responses, and blocking dangerous behavior before it completes. Not in a log you review tomorrow. Right now.

Synopsis

firmis monitor [subcommand] [options]

Subcommands

Subcommand	Description
`start`	Start the monitoring daemon
`stop`	Stop the monitoring daemon
`status`	Show daemon status, adapter health, and recent events

Description

firmis monitor works through two independent channels. The first is an MCP proxy: firmis monitor --wrap "<mcp-command>" replaces your MCP server command and sits between your client and server, inspecting every message in both directions. The second is a persistent daemon that coordinates monitoring state, correlates events across channels, and provides the socket endpoint for hook integration.

Monitor watches every agent in your stack. Free detects threats and keeps 24 hours of history. Pro adds automatic blocking with 7 days of history. Business adds policy enforcement with 90 days of history. Every plan monitors unlimited agents.

Monitoring complements static scanning. Use firmis scan to audit what your agent configs say, and firmis monitor to observe what they actually do at runtime.

Examples

First-time setup: install everything and start daemon

npx firmis-cli monitor --install

Check current status

npx firmis-cli monitor status

Wrap a specific MCP server (log-only mode)

npx firmis-cli monitor --wrap "npx @github/mcp-server /tmp"

Wrap an MCP server and block threats above high severity

npx firmis-cli monitor --wrap "npx @github/mcp-server /tmp" --block --severity high

Install hooks for Claude Code only

npx firmis-cli monitor --install-hooks --platform claude-code

Start the daemon in detect-only mode (free tier)

npx firmis-cli monitor start --automation-level audit-only

Check behavioral event status

npx firmis-cli monitor --behavioral-status

Remove all monitoring

npx firmis-cli monitor --uninstall

How it works

Transport layer

The MCP proxy intercepts tool calls via stdio, sitting transparently between your client and server. Platform-specific hooks integrate directly with your agent runtime.

Platform adapters

Firmis ships adapters for each supported platform:

Claude Code - hooks into PreToolUse and PostToolUse events
Gemini CLI - hook integration for tool call interception
Cursor - hook integration for tool call interception
OpenClaw - hook integration for tool call interception
MCP servers - stdio proxy wraps any MCP server command

Decision engine

Every tool call is evaluated against behavioral baselines and policy rules. Three automation levels control how the engine responds:

Full (full) - detect + block threats automatically
Semi (semi) - detect threats, require confirmation before blocking
Audit-only (audit-only) - detect threats, log without enforcement

What it detects

The monitor covers a broad set of threat categories:

Credential exfiltration
Config poisoning
Reverse shells
Supply chain attacks
Prompt injection
Data exfiltration
Persistence mechanisms
CI pipeline poisoning
Git manipulation
Reconnaissance
Agent infiltration
Security bypass

Response inspection

The monitor inspects tool call responses (not just requests) for signs of compromise. This catches credential leaks, injection attempts embedded in tool output, and other post-execution threats that request-only monitoring misses.

Cross-channel correlation

Events from multiple sources (MCP proxy, platform hooks, daemon) are correlated to detect multi-step attacks. An injection in a tool response followed by an unexpected network call is a pattern neither channel catches alone.

Behavioral baseline

After observing normal usage, the monitor flags deviations: unusual tool call sequences, unexpected file access patterns, and anomalous activity that breaks from established patterns.

Automatic response escalation

The decision engine assigns a threat level to each event and escalates accordingly:

NORMAL      ->  Log the event
ELEVATED    ->  Log + warn in terminal
HIGH        ->  Log + warn + require confirmation
LOCKDOWN    ->  Block the tool call entirely

Intelligence tiers

Every plan monitors unlimited agents. Tiers differ by what the monitor does when it detects a threat, and how long history is retained.

Free: Monitor unlimited agents — detect threats, 24-hour history

Full visibility into what every agent is doing. Detects threats and logs every security event so you know exactly what happened and when.

Monitor all agents, no limits
Detect threats across all categories
Log events to ~/.firmis/
Build behavioral baseline
Alert on new patterns and file changes
Review configuration changes
24-hour event retention

firmis monitor start --automation-level audit-only

Pro: Monitor unlimited agents — detect + block threats, 7-day history

Stop dangerous behavior before it completes. Detects threats and automatically blocks them based on policy rules, with behavioral anomaly detection and active enforcement. Pro and Business include a 14-day free trial — start with firmis monitor --start-daemon after signing up.

Everything in Free
Block threats matching policy rules
Behavioral anomaly detection
Configurable severity thresholds
7-day event retention

firmis monitor start --automation-level full

Business: Monitor unlimited agents — detect + block + enforce policies, 90-day history

Organization-wide threat detection and policy enforcement with cross-channel correlation, custom policies, and team visibility.

Everything in Pro
Cross-channel event correlation
Custom policy rules
Advanced persistent threat detection
Cloud sync to workspace for team visibility
90-day event retention

Custom: Monitor unlimited agents — fleet-wide + webhooks, custom history

Enterprise-grade monitoring for large deployments.

Everything in Business
Fleet-wide agent monitoring dashboard
Webhook integrations for SIEM/SOAR
Custom retention periods
Dedicated support

Options

Flag	Type	Default	Description
`--wrap <command>`	string	-	Command to spawn as downstream MCP server. Firmis proxy intercepts all messages between client and server.
`--server-name <name>`	string	auto-derived	Label for this server instance in logs and events
`--block`	boolean	`false`	Block tool calls matching policy. Requires Pro (active blocking).
`--severity <level>`	enum	`high`	Minimum severity to act on when `--block` is enabled: `low`, `medium`, `high`, `critical`
`--log-file <path>`	string	`~/.firmis/monitor.log`	Custom event log file path
`--verbose`	boolean	`false`	Print every intercepted call to stderr
`--install`	boolean	`false`	Install all monitoring: MCP proxy config + agent hooks + daemon. Recommended for first-time setup. Requires Pro (active blocking).
`--uninstall`	boolean	`false`	Remove all monitoring components and restore original MCP configs
`--install-hooks`	boolean	`false`	Install Firmis hooks into detected agent platforms. Free tier.
`--platform <name>`	string	auto-detect	Target platform for `--install-hooks`: `claude-code`, `gemini-cli`, `cursor`, `openclaw`, `all`
`--automation-level <level>`	enum	`full`	Decision mode: `full` (detect + block), `semi` (detect, confirm before block), `audit-only` (detect only, free tier)
`--behavioral-status`	boolean	`false`	Show behavioral event count, session count, and scoring status. Free tier.
`--start-sidecar`	boolean	`false`	Start scoring sidecar for behavioral anomaly detection. Requires Pro.
`--stop-sidecar`	boolean	`false`	Stop the scoring sidecar
`--label <args>`	string	-	Label a behavioral event for training: `"<event-id> normal"` or `"<event-id> anomalous"`

Rugpull detection

Firmis captures a baseline of your agent configurations and detects when they change unexpectedly (supply chain “rug pull” attacks).

Flag	Description
`--review-changes`	Review detected configuration changes
`--approve <server>`	Approve legitimate changes to update baseline
`--reject <server>`	Reject and revert suspicious changes

$ firmis monitor --review-changes

Detected changes since last baseline:
  1. mcp-server-fetch: tool description modified
  2. claude-skill-deploy: new permission requested (fs:write)

Review each change? [Y/n]

Cloud sync

When logged in, monitor events sync to your Firmis workspace for team visibility. This gives your team a shared view of agent behavior across environments without requiring everyone to check local logs.

Environment file protection

A dedicated runtime rule blocks attempts to write to .env files (.env, .env.production, .env.local), preventing credential injection attacks like replacing DATABASE_URL with a malicious connection string.

This rule is active by default in all monitor modes.

Setup

# First-time setup: install hooks and start daemon
npx firmis-cli monitor --install

# Check that everything is running
npx firmis-cli monitor status

# When you want to stop
npx firmis-cli monitor --uninstall

The daemon runs as a lightweight background process. Hook latency is under 100ms, imperceptible during normal agent use.

When to use this

High-stakes environments: Agents with access to production systems, financial data, or credential stores need runtime protection. Static scanning alone is not enough.
After a supply chain incident: If a dependency is flagged for malicious behavior, runtime monitoring can detect and block that behavior even before you update.
Regulated workloads: Some compliance frameworks require evidence of runtime controls, not just static analysis.
Before you trust a new tool: Install a new MCP server and run the monitor to observe actual behavior before giving it full access.

Exit codes

Code	Meaning
`0`	Command completed (status check, install, stop, etc.)
`1`	Error: higher tier required for this feature, invalid options, or daemon failure