fsr-agentic-toolkit 0.1.0__py3-none-any.whl

fsr_agentic_toolkit/__init__.py

@@ -0,0 +1,10 @@
+"""FSR Agentic Toolkit: the agent layer for FortiSOAR.
+
+pyfsr is the SDK. fsr_playbooks is the domain (compiler, validators, catalog).
+This package is the agent layer on top of both: seven workflows that return one
+evidence-backed result, the SDK verbs, one gate, one MCP server and one CLI. The
+SOC Assistant connector is built on the same pieces.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

fsr_agentic_toolkit/cli.py

@@ -0,0 +1,130 @@
+"""``fsr-agentic-toolkit``: the same tools as the MCP server, from a shell.
+
+    fsr-agentic-toolkit init --url fortisoar.example.com --api-key <key>
+    fsr-agentic-toolkit mcp                         # the MCP server (stdio)
+    fsr-agentic-toolkit tools                       # what the gate lets through
+    fsr-agentic-toolkit debug-run --playbook-or-id "Close Alert"
+    fsr-agentic-toolkit orient --modules alerts,heists --json
+    fsr-agentic-toolkit call search_records '{"module": "alerts", "limit": 5}'
+
+Every workflow is a subcommand; its flags are the tool's arguments (objects and
+lists as JSON, lists also comma-separated). Calls go through the one dispatch
+and gate, and a workflow prints the same WorkflowResult the MCP tool returns
+(text by default, ``--json`` for the tool envelope). The box comes from the
+``FSR_*`` environment or ``--instance`` (an alias in ``~/.pyfsr/instances.toml``).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .workflow_tools import WORKFLOW_SPECS
+
+
+def _client(instance: str | None) -> Any:
+    from pyfsr.instances import InstanceRegistry
+
+    return InstanceRegistry.load().client(instance)
+
+
+def _value(raw: str, schema: dict[str, Any]) -> Any:
+    kind = schema.get("type")
+    if kind in ("object", "array"):
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            if kind == "array":
+                return [p.strip() for p in raw.split(",") if p.strip()]
+            raise
+    if kind == "boolean":
+        return raw.strip().lower() in ("1", "true", "yes", "on")
+    if kind == "integer":
+        return int(raw)
+    if kind == "number":
+        return float(raw)
+    return raw
+
+
+def _print_result(out: Any, as_json: bool) -> int:
+    from .workflows.result import WorkflowResult, render_text
+
+    if as_json or not isinstance(out, dict) or "workflow" not in out:
+        print(json.dumps(out, indent=2, default=str))
+        return 0 if not (isinstance(out, dict) and "error" in out) else 1
+    result = WorkflowResult.model_validate({k: v for k, v in out.items() if k != "ok"})
+    print(render_text(result))
+    return 0 if result.status != "blocked" else 1
+
+
+def _add_workflow(sub: argparse._SubParsersAction, spec: Any) -> None:
+    name = spec.name.replace("_", "-")
+    p = sub.add_parser(name, help=spec.description.split(". ")[0] + ".")
+    props = spec.rendered_schema().get("properties") or {}
+    required = set(spec.input_schema.get("required") or [])
+    for arg, schema in props.items():
+        p.add_argument(f"--{arg.replace('_', '-')}", dest=arg, required=arg in required,
+                       metavar=str(schema.get("type", "value")).upper(),
+                       help=schema.get("description"))
+    p.add_argument("--instance", help="configured instance alias")
+    p.add_argument("--json", action="store_true", help="print the tool envelope as JSON")
+    p.set_defaults(func=_run_tool, tool=spec.name, schema_props=props)
+
+
+def _run_tool(args: argparse.Namespace) -> int:
+    from .verbs.tools import dispatch
+
+    arguments = {k: _value(getattr(args, k), s) for k, s in args.schema_props.items()
+                 if getattr(args, k, None) is not None}
+    return _print_result(dispatch(_client(args.instance), args.tool, arguments), args.json)
+
+
+def _call(args: argparse.Namespace) -> int:
+    from .verbs.tools import dispatch
+
+    arguments = json.loads(args.arguments) if args.arguments else {}
+    return _print_result(dispatch(_client(args.instance), args.tool, arguments), args.json)
+
+
+def _tools(args: argparse.Namespace) -> int:
+    from .verbs.tools import enabled_tools
+
+    for spec in enabled_tools():
+        print(f"{spec.name:32} tier {spec.tier}  {spec.description.split('. ')[0]}")
+    return 0
+
+
+def _mcp(args: argparse.Namespace) -> int:
+    from .verbs.mcp import main as serve
+
+    serve()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    from . import init_cmd
+
+    parser = argparse.ArgumentParser(prog="fsr-agentic-toolkit", description=__doc__.split("\n")[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    init_cmd.build_subparser(sub)
+    sub.add_parser("mcp", help="run the MCP server on stdio").set_defaults(func=_mcp)
+    sub.add_parser("tools", help="list the tools the gate allows, with their tier").set_defaults(func=_tools)
+    p_call = sub.add_parser("call", help="call any tool by name with JSON arguments")
+    p_call.add_argument("tool")
+    p_call.add_argument("arguments", nargs="?", default="")
+    p_call.add_argument("--instance")
+    p_call.add_argument("--json", action="store_true")
+    p_call.set_defaults(func=_call)
+    for spec in WORKFLOW_SPECS:
+        _add_workflow(sub, spec)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args) or 0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

fsr_agentic_toolkit/init_cmd.py

@@ -0,0 +1,161 @@
+"""``fsr-agentic-toolkit init`` -- wire a coding agent to a FortiSOAR box.
+
+``fsr-agentic-toolkit init`` is the one-command bootstrap: verify the connection with a
+real whoami call, optionally save the settings to an env file, and print the
+MCP config snippet for the agent product in use (Claude Code, OpenCode, GitHub
+Copilot). The snippets launch the toolkit's MCP server (``fsr-agentic-toolkit
+mcp``), preferring the locally installed executable and falling back to
+``uvx --from fsr-agentic-toolkit``.
+
+Safety env vars an agent setup may add to the snippet's ``env`` block:
+``FSR_MCP_READONLY=1``, ``FSR_MCP_ALLOW_TOOLS``, ``FSR_MCP_DENY_TOOLS`` (see
+:mod:`fsr_agentic_toolkit.verbs.tools`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+def _server_command() -> tuple[str, list[str]]:
+    """The command + args that launch the toolkit MCP server on this machine."""
+    exe = shutil.which("fsr-agentic-toolkit")
+    if exe:
+        return exe, ["mcp"]
+    return "uvx", ["--from", "fsr-agentic-toolkit", "fsr-agentic-toolkit", "mcp"]
+
+
+def _env_block(args: argparse.Namespace) -> dict[str, str]:
+    env = {"FSR_BASE_URL": args.url, "FSR_API_KEY": args.api_key}
+    if args.no_verify_ssl:
+        env["FSR_VERIFY_SSL"] = "false"
+        env["FSR_SUPPRESS_INSECURE_WARNINGS"] = "true"
+    if args.readonly:
+        env["FSR_MCP_READONLY"] = "1"
+    return env
+
+
+def _claude_code_snippet(args: argparse.Namespace) -> str:
+    command, cmd_args = _server_command()
+    cfg = {
+        "mcpServers": {
+            "fortisoar": {
+                "command": command,
+                **({"args": cmd_args} if cmd_args else {}),
+                "env": _env_block(args),
+            }
+        }
+    }
+    return "# .mcp.json (project root), or merge into ~/.claude.json\n" + json.dumps(cfg, indent=2)
+
+
+def _opencode_snippet(args: argparse.Namespace) -> str:
+    command, cmd_args = _server_command()
+    cfg = {
+        "mcp": {
+            "fortisoar": {
+                "type": "local",
+                "command": [command, *cmd_args],
+                "environment": _env_block(args),
+                "enabled": True,
+            }
+        }
+    }
+    return "# opencode.json (project root) -- merge the 'mcp' key\n" + json.dumps(cfg, indent=2)
+
+
+def _copilot_snippet(args: argparse.Namespace) -> str:
+    command, cmd_args = _server_command()
+    cfg = {
+        "servers": {
+            "fortisoar": {
+                "command": command,
+                **({"args": cmd_args} if cmd_args else {}),
+                "env": _env_block(args),
+            }
+        }
+    }
+    return "# .vscode/mcp.json (VS Code / GitHub Copilot agent mode)\n" + json.dumps(cfg, indent=2)
+
+
+_SNIPPETS = {
+    "claude-code": _claude_code_snippet,
+    "opencode": _opencode_snippet,
+    "copilot": _copilot_snippet,
+}
+
+
+def _verify(args: argparse.Namespace) -> dict | None:
+    """whoami against the box; None (with a printed error) when unreachable."""
+    from pyfsr.client import FortiSOAR
+
+    try:
+        client = FortiSOAR(
+            args.url,
+            token=args.api_key,
+            verify_ssl=not args.no_verify_ssl,
+            suppress_insecure_warnings=args.no_verify_ssl,
+        )
+        return client.users.whoami()
+    except Exception as exc:  # noqa: BLE001 - report, don't trace
+        print(f"error: could not verify the connection: {exc}", file=sys.stderr)
+        return None
+
+
+def _write_env_file(path: Path, args: argparse.Namespace) -> None:
+    lines = [f"{k}={v}" for k, v in _env_block(args).items()]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Create with 0600 from the first byte (no write-then-chmod exposure window).
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        fh.write("\n".join(lines) + "\n")
+    os.chmod(path, 0o600)  # an O_TRUNC of a pre-existing looser file keeps its old mode
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    me = _verify(args)
+    if me is None:
+        if not args.skip_verify:
+            print("hint: re-run with --skip-verify to print the snippets anyway", file=sys.stderr)
+            return 1
+        print("continuing despite failed verification (--skip-verify)", file=sys.stderr)
+    else:
+        print(f"connected: {me.get('loginid')} <{me.get('email')}> @ {args.url}")
+
+    if args.save_env:
+        path = Path(args.save_env).expanduser()
+        _write_env_file(path, args)
+        print(f"saved credentials to {path} (mode 600)")
+
+    products = [p for p in _SNIPPETS if getattr(args, p.replace("-", "_"))]
+    if not products:
+        products = ["claude-code"]
+    for product in products:
+        print(f"\n--- {product} ---")
+        print(_SNIPPETS[product](args))
+    print(
+        "\nsafety: add FSR_MCP_READONLY=1 to the env block for a read-only surface, "
+        "or FSR_MCP_ALLOW_TOOLS/FSR_MCP_DENY_TOOLS to narrow it. Destructive tools "
+        "always need confirm=true."
+    )
+    return 0
+
+
+def build_subparser(sub: argparse._SubParsersAction) -> None:
+    """Wire the ``agent`` subcommands onto an existing subparsers object."""
+    p_init = sub.add_parser("init", help="verify a box and print the MCP setup snippet for your coding agent")
+    p_init.add_argument("--url", required=True, help="FortiSOAR base URL, e.g. fortisoar.example.com")
+    p_init.add_argument("--api-key", required=True, help="API key (Settings > API Keys on the appliance)")
+    p_init.add_argument("--no-verify-ssl", action="store_true", help="disable TLS verification (lab boxes)")
+    p_init.add_argument("--readonly", action="store_true", help="bake FSR_MCP_READONLY=1 into the snippet")
+    p_init.add_argument("--save-env", metavar="PATH", help="also write the FSR_* values to this env file (mode 600)")
+    p_init.add_argument("--skip-verify", action="store_true", help="print snippets even if whoami fails")
+    p_init.add_argument("--claude-code", action="store_true", help="print the Claude Code .mcp.json snippet (default)")
+    p_init.add_argument("--opencode", action="store_true", help="print the OpenCode opencode.json snippet")
+    p_init.add_argument("--copilot", action="store_true", help="print the VS Code / Copilot .vscode/mcp.json snippet")
+    p_init.set_defaults(func=cmd_init)