fsr-agentic-toolkit

Workflows and tools that make an AI agent competent on FortiSOAR. One registry and one safety gate, served three ways: an MCP server, a CLI, and a Python API.

Where it sits

pyfsr               SDK: typed REST client, auth, instances. No agent code.
fsr_playbooks       Domain: playbook YAML, validation, compile, run analysis.
fsr-agentic-toolkit Agent layer: verbs + seven workflows, MCP server, CLI.   <- this repo
products            SOC assistant connector, widgets, workshops.

Each layer depends only on the ones above it. The SOC assistant connector can register the workflows into its own dispatch with fsr_agentic_toolkit.workflow_tools.register_into_framework(). They stay hidden from its model until the host opts in.

The seven workflows

Each one returns a WorkflowResult: findings with evidence ids, unknowns, next steps with their tier, and an id that a follow-up workflow can take. Use cases compose them. A custom module plus a playbook that acts on it is provision_module, then build_playbook, then verify_effect.

API only

The toolkit talks to FortiSOAR through its REST API and nothing else. It has no SSH, shell, log or database tools. Appliance shell tools are a human CLI: pyfsr appliance ....

Safety

Every call goes through one gate. Writes are tier 2. Destructive tools are tier 3 and need confirm: true. Environment policy:

• FSR_MCP_READONLY=1 drops every write.
• FSR_MCP_ALLOW_TOOLS / FSR_MCP_DENY_TOOLS take comma-separated names.

Install and use

pip install fsr-agentic-toolkit
fsr-agentic-toolkit init --url fortisoar.example.com --api-key <key>
fsr-agentic-toolkit tools
fsr-agentic-toolkit orient --modules alerts --json
fsr-agentic-toolkit debug-run --playbook-or-id "Close Alert"
fsr-agentic-toolkit call search_records '{"module": "alerts", "limit": 5}'
fsr-agentic-toolkit mcp        # MCP server on stdio

The box comes from FSR_* environment variables or --instance <alias> from ~/.pyfsr/instances.toml. An explicit FSR_BASE_URL wins over the default alias.

Development

One-command setup and the test loop CI runs (Python 3.11+):

make install    # editable install + test/lint deps into .venv
make test       # the full suite (what CI runs)
make lint       # ruff (also enforced in CI)

Or by hand, matching CI exactly:

pip install -e ".[test]"
python -m pytest -q

Note the [test] extra: pip install -e . alone does not pull in pytest.