automateyournetwork/fortianalyzer-ops

FortiAnalyzer Operations — the analyzer plane

MCP Server

• Server: fortinet-mcp (NetClaw-authored, spec 080 / roadmap R3)
• Command: $FORTINET_MCP_CMD
• Transport: stdio · JSON-RPC over /jsonrpc (the same dialect FortiManager speaks)
• Requires: FORTIANALYZER_HOST, FORTIANALYZER_API_TOKEN (FortiAnalyzer 7.2.2+ for token auth)
• Mode: read-only

The one rule that matters most here

"No logs matched" is NOT "this rule is unused."

This skill exists to answer "is this rule dead?" — and that question is dangerously easy to answer wrongly. An empty result can mean:

• nothing matched in the window you queried (retention is finite; history is not)
• the device never forwarded logs to this analyzer at all
• logging is disabled on the rule itself

Reporting any of those as "unused" would license someone to delete a live firewall rule. So an empty result returns the explicit outcome no_logs_in_window, never ok and never an error, with a message saying what it does and does not prove.

This is the same error class as spec 078's "no advisories ≠ not vulnerable" and spec 079's "no probes found ≠ outage", and it gets the same treatment: a separate, named outcome that cannot be silently collapsed.

Where this plane sits

| Question | Plane | Skill | |---|---|---| | "Has anything actually matched this rule?" | analyzer | this skill | | "What policy is intended?" | manager | fortimanager-ops | | "What is the box running right now?" | device | fortigate-ops |

The manager knows a rule exists. Only the analyzer knows whether anyone ever matched it. A configured rule is not a used rule.

Tools (4, all read-only)

| Tool | What it answers | |---|---| | faz_query_logs | Traffic logs matching a filter within a bounded window | | faz_fetch_more | Next page, re-run at an offset | | faz_policy_activity | Did anything match policy N in this window? | | faz_list_devices | Which devices forward logs here — check this first |

Time windows are mandatory and always stated

If you supply no window, the tools apply the last 24 hours and say so in scope.window_start / scope.window_end and in notes. An unbounded log query against a busy analyzer is slow, expensive, and produces a result nobody can interpret because they do not know what period it covers.

Every response echoes the window actually queried, not the one requested.

Pagination

faz_fetch_more re-runs the search at a new offset. It does not reuse FortiAnalyzer's search task id (tid), because those are single-use and expire — treating one as a durable cursor produces silent truncation, where you believe you have all the results and you have some of them.

Workflow: is this firewall rule dead?

1. faz_list_devices — confirm the device that owns the rule actually forwards logs here. If it does not, stop: an empty result would mean nothing.
2. faz_policy_activity with the policy id and an explicit, generous window.
3. Read the outcome:
   • ok with sessions_matched > 0 → the rule is live. Do not remove it.
   • no_logs_in_window → nothing matched in that window. Not proof of disuse.
4. Before concluding a rule is unused, verify: log forwarding on, retention covers the period, logging enabled on the rule itself.
5. Only then treat it as a removal candidate — and route the actual change through fortimanager-ops, which enforces the two write gates.

Workflow: what hit this policy?

1. faz_query_logs with filter_expr (e.g. policyid=12) and a bounded window.
2. Page with faz_fetch_more using the returned next_offset while has_more.
3. Correlate sources and destinations against fmg_resolve_object to check whether the traffic matches what the rule intended to permit.

Every response carries its plane and scope

{ "plane": "analyzer",
  "scope": {"adom": "root", "window_start": "...", "window_end": "..."},
  "outcome": "no_logs_in_window", "message": "... This is NOT evidence the rule is unused." }

The window is part of the scope, not an optional detail. A log result without its window is uninterpretable, so a response that cannot state one is an error.

Integration with other skills

| Skill | How they compose | |---|---| | fortimanager-ops | Find the rule (intent), then come here for whether it was used | | fortigate-ops | Device state; use together to separate "not configured" from "not used" | | fwrule-analyzer | Shadowed rules found there + zero activity here = strong removal case | | servicenow-change-workflow | Rule removal is a production change — CR required | | gait-session-tracking | Every query here is GAIT-audited automatically |

Important rules

• Never report an empty window as "unused".
• Always state the window you queried, including the default.
• Check faz_list_devices before trusting silence.
• Read-only — findings here justify a change; they never make one.