fsr_playbooks
A FortiSOAR playbook authoring & compiler framework:
- Compiler -- turn readable YAML into FortiSOAR playbook JSON (parser → resolver → validator → emitter), round-trip lossless with structured diagnostics.
- Agent -- LLM co-authoring helpers for building and triaging playbooks.
- MCP server -- tools that expose the compiler, connector/Jinja reference, and playbook authoring to MCP-compatible clients.
Install
pip install fsr_playbooks # base: compiler + agent
pip install "fsr_playbooks[llm]" # + OpenAI / Anthropic providers
pip install "fsr_playbooks[mcp]" # + MCP server (implies [llm])
Requires Python 3.10+.
End-to-end: author → compile → deploy → run
1. Author a playbook in YAML
The compiler input is a readable collection of playbooks. A minimal one
(start → set_variable → connector):
# hello_connector.yaml
collection: Compiler Demo
description: Smallest possible end-to-end -- start, set a variable, call a connector.
visible: true
playbooks:
- name: Hello Connector
description: Demonstrates start -> set_variable -> connector flow.
steps:
- name: Start
type: start
next: Prepare inputs
- name: Prepare inputs
type: set_variable
next: Get organization
vars:
target_org: "Fortinet"
- name: Get organization
type: connector
connector: fortinet-fortisiem
operation: get_org_name_by_org_id
config: ""
params:
domain_id: "{{ vars.target_org }}"
2. Compile it to FortiSOAR playbook JSON
from pathlib import Path
from fsr_playbooks import compile_yaml
# The reference DB resolves connectors, operations, params, step types, and
# Jinja. It ships with the full framework repo (data/fsr_reference.db), NOT
# the PyPI wheel -- point this at your copy.
REFERENCE_DB = Path("data/fsr_reference.db")
text = Path("hello_connector.yaml").read_text()
result = compile_yaml(text, REFERENCE_DB)
if not result.ok:
for err in result.errors: # structured, never raises
print(f"[{err.severity}] {err.code}: {err.message} ({err.path})")
raise SystemExit("compile failed")
collection = result.fsr_json["data"][0] # the FortiSOAR collection entity
compile_yaml(text, db_path, lax_codes=None) -> CompileResult returns a result
object with .ok, .fsr_json ({"data": [collection]}), .errors,
.warnings, and .ir (the parsed tree) -- it reports problems as structured
CompileErrors rather than raising.
3. Deploy the collection to a FortiSOAR instance
Pushing and triggering talk to a live FortiSOAR REST API, so they use the
pyfsr client (pip install pyfsr) -- this
package does the compiling, pyfsr does the transport.
from pyfsr import FortiSOAR
client = FortiSOAR(
base_url="https://your-fortisoar-host",
auth="<api-key>", # or ("username", "password")
verify_ssl=True,
)
# Push the compiled collection. The compiler-assigned uuid is preserved, so
# re-deploys can target it with client.workflow_collections.update(uuid, ...)
# / .delete(uuid).
client.workflow_collections.create(
name=collection["name"],
description=collection.get("description", ""),
visible=collection.get("visible", True),
uuid=collection["uuid"],
workflows=collection["workflows"], # full workflow objects (steps + routes)
record_tags=collection.get("recordTags"),
)
4. Trigger the playbook and wait for it
result = client.playbooks.run_and_wait("Hello Connector", inputs={})
print(result.status) # 'finished' / 'failed' / 'terminated'
print(result.succeeded) # True iff status == 'finished'
for step in result.steps:
print(f" {step.name:40} {step.status:10} {step.duration_ms or 0:6}ms")
if result.failure:
print("failed at:", result.failure.failing_step, "-", result.failure.error_message)
What needs what: step 2 (compile) is pure
fsr_playbooks+ the reference DB. Steps 3-4 (deploy/run) additionally needpyfsrand a reachable FortiSOAR instance.run_and_waittriggers, polls to terminal, and returns a typedRunResultwith per-step timing and failure details in one call.
Extras
| Extra | Adds | Use for |
|---|---|---|
| (base) | pyyaml, ruamel.yaml, jinja2, pydantic |
YAML → FSR JSON compilation |
[llm] |
openai, anthropic, httpx |
LLM-assisted authoring / triage |
[mcp] |
mcp (+ [llm]) |
running the MCP server tools |
License
MIT -- see LICENSE.
Links
Note: the MCP server's live-execution / recipe tools depend on the reference store and probe helpers that ship with the full framework repo, not this package alone. The compiler, agent, and the rest of the MCP surface work standalone.
1 maintainer
Metadata
1 maintainer
Release files for fsr-playbooks 0.7.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fsr_playbooks-0.7.4-py3-none-any.whl | Python 3 | none | any | Details |
Release files / fsr_playbooks-0.7.4-py3-none-any.whl
| Download URL | fsr_playbooks-0.7.4-py3-none-any.whl |
|---|---|
| Size | 1.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5d987359b0ea2cfd966d955c114ea293edf6dd581cfc0570eaeda80f54cbc3b7
|
|
BLAKE2b-256 checksum How to use checksums |
ac45efeb1a18618282b63367fe13acc6797530595c3fe2c757cf3703b7802f98
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logSecurity for fsr-playbooks 0.7.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 1 file in this release has been uploaded with provenance metadata.
Attestation for fsr_playbooks-0.7.4-py3-none-any.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
