HFortix-FortiManager

HFortix-FortiManager is a modern, fully-typed Python SDK for the FortiManager JSON-RPC API — 2,376 endpoints generated from the official FMG 7.6.6 API specification, with full .pyi type stubs for IDE autocomplete on every call.

🚀 Quick Start

pip install hfortix-fortimanager

from hfortix_fortimanager import FortiManager

# API key auth (FMG 7.4.7+ / 7.6.2+) — no login/logout needed
fmg = FortiManager(host="fmg.example.com", api_key="your-api-key")

# Session auth — context manager handles login/logout
with FortiManager(host="fmg.example.com", username="admin", password="pw") as fmg:
    # Device inventory
    devices = fmg.api.dvmdb.adom.device.get(adom="root")
    for dev in devices:
        print(dev.name, dev.ip, dev.os_ver)

    # Firewall address objects (ADOM-scoped)
    fmg.api.pm.config.adom.obj.firewall.address.add(
        adom="root",
        name="web-server",
        subnet=["10.0.1.100", "255.255.255.255"],
    )

    # Firewall policy in a policy package — with placement control
    fmg.api.pm.config.adom.pkg.firewall.policy.add(
        adom="root",
        pkg="default",
        name="Allow-Web",
        srcintf=["port1"], dstintf=["port2"],
        srcaddr=["all"], dstaddr=["web-server"],
        service=["HTTPS"], action="accept", schedule=["always"],
        before="42",   # insert before policyid 42 (omit to append)
    )

✨ Key Features

• 🎯 2,376 endpoints — Device DB (dvmdb), Policy & Objects (pm: ADOM objects, device-level config, policy packages, policy blocks, system/WAN templates), and task monitoring
• 💪 Fully typed — .pyi stubs for every endpoint; Literal[...] enums for every documented value; PEP 561 py.typed
• 🔑 Dual auth — session (username/password with automatic re-login) or API key (Bearer, FMG 7.4.7+/7.6.2+, incl. api_user for 7.6.6+)
• 🧭 Navigation mirrors the API — URL scoping segments are kept: /pm/config/adom/{adom}/obj/firewall/address → fmg.api.pm.config.adom.obj.firewall.address
• 📦 Minimal payloads — only the parameters you pass are sent; FMG applies its own server-side defaults (no surprise field writes)
• 🛡️ Production plumbing from hfortix-core — retry with backoff, optional rate limiting and circuit breaker, audit logging, sanitized logs
• 🔒 Workspace mode — dvmdb.adom.workspace lock / commit / unlock endpoints for ADOMs in workspace mode

🧰 GET options

All JSON-RPC read options are typed parameters:

fmg.api.dvmdb.adom.device.get(
    adom="root",
    fields=["name", "ip", "os_ver"],
    filter=["conf_status", "==", "insync"],
    range=[0, 50],
    loadsub=0,
)

🪄 Escape hatch — raw JSON-RPC

Anything not (yet) exposed as a typed endpoint can be called directly:

result = fmg.client.execute(
    method="exec",
    params=[{"url": "/securityconsole/install/package",
             "data": {"adom": "root", "pkg": "default"}}],
)

⚠️ Known limitations (0.1.x)

• No securityconsole / install-deploy endpoints yet — configuration management is fully covered, but installing policy packages to devices currently requires the raw fmg.client.execute() escape hatch (see above). Planned for an upcoming release.
• model_registry / as_models() / typed response models are experimental placeholders — they currently return None / fall back to generic objects.
• Sync only — no async client yet (unlike hfortix-fortios).

🔗 Related Packages

This package is part of the HFortix SDK ecosystem:

• hfortix-core — Core HTTP client and utilities
• hfortix-fortios — FortiOS/FortiGate SDK
• hfortix — Meta package

📄 License

Proprietary license. All rights reserved.

🤝 Support

• Issues: https://github.com/hermanwjacobsen/hfortix-fortimanager/issues
• PyPI: https://pypi.org/project/hfortix-fortimanager/

Version: 0.1.0 (Alpha)
FortiManager Support: 7.6.6 (specs; 7.4.x compatible)
Python: 3.10+