hfortix-fortios 0.5.159

Type-safe Python client for FortiGate automation and FortiOS REST API - 1,348+ endpoints with async support and atomic transactions

HFortix FortiOS

Complete Python SDK for FortiOS/FortiGate automation - 1,300+ API endpoints with full type hints

📦 Overview

hfortix-fortios provides a comprehensive, production-ready Python client for FortiOS/FortiGate firewalls. Auto-generated from official FortiOS 7.6.5 schemas with complete type safety and IDE autocomplete.

Key Features

• ✅ 1,300+ API Endpoints - Complete FortiOS REST API coverage (CMDB, Monitor, Log, Service)
• 🎯 Full Type Hints - Perfect IDE autocomplete with .pyi stub files
• 🔄 Async/Await Support - High-performance asynchronous operations
• 📘 Auto-generated - From official Fortinet schemas (FortiOS 7.6.5)
• 🛡️ Production Ready - Transaction support, error handling, retries
• 🎨 Pythonic API - Clean, intuitive interface

🚀 Installation

# Install fortios package (includes hfortix-core automatically)
pip install hfortix-fortios

# Or install via meta-package
pip install hfortix[fortios]

💡 Quick Start

Basic Usage

from hfortix_fortios import FortiOS

# Connect to FortiGate
fgt = FortiOS(
    host="192.168.1.99",
    token="your-api-token",
    verify=False  # Optional: disable SSL verification
)

# Get all firewall policies
policies = fgt.api.v2.cmdb.firewall.policy.get()

for policy in policies:
    print(f"Policy {policy.policyid}: {policy.name}")

# Create a firewall address
fgt.api.v2.cmdb.firewall.address.post(
    name="web-server",
    subnet="192.168.1.100 255.255.255.255",
    comment="Production web server"
)

# Update an address
fgt.api.v2.cmdb.firewall.address.put(
    name="web-server",
    comment="Updated comment"
)

# Delete an address
fgt.api.v2.cmdb.firewall.address.delete(name="web-server")

Async Usage

from hfortix_fortios import AsyncFortiOSClient

async def main():
    async with AsyncFortiOSClient(
        host="192.168.1.99",
        token="your-api-token"
    ) as client:
        # Get system status
        status = await client.api.v2.monitor.system.status.get()
        print(f"Hostname: {status.hostname}")
        
        # Get all interfaces
        interfaces = await client.api.v2.monitor.system.interface.select().get()
        for iface in interfaces:
            print(f"{iface.name}: {iface.ip}")

asyncio.run(main())

FortiManager Proxy

Manage FortiGate devices through FortiManager:

from hfortix_fortios import FortiManagerProxy

# Connect to FortiManager
fmg = FortiManagerProxy(
    host="fortimanager.example.com",
    username="admin",
    password="password",
    adom="root"
)

# Get proxied connection to managed device
fgt = fmg.get_device("firewall-01")

# Use same API as direct FortiOS connection
addresses = fgt.api.v2.cmdb.firewall.address.get()

# Clean up
fmg.logout()

📚 API Structure

The client provides access to all FortiOS API endpoints organized by category:

client.api.v2.cmdb.*       # Configuration Management Database (CMDB)
client.api.v2.monitor.*    # Monitor endpoints (real-time data)
client.api.v2.log.*        # Log endpoints (disk, memory, cloud)
client.api.v2.service.*    # Service endpoints (sniffer, security rating)

Common Endpoints

# Firewall
client.api.v2.cmdb.firewall.policy.*
client.api.v2.cmdb.firewall.address.*
client.api.v2.cmdb.firewall.addrgrp.*
client.api.v2.cmdb.firewall.service.custom.*

# System
client.api.v2.cmdb.system.interface.*
client.api.v2.cmdb.system.global_.*
client.api.v2.monitor.system.status.*
client.api.v2.monitor.system.interface.*

# VPN
client.api.v2.cmdb.vpn.ipsec.phase1_interface.*
client.api.v2.cmdb.vpn.ipsec.phase2_interface.*
client.api.v2.monitor.vpn.ipsec.*

# Router
client.api.v2.cmdb.router.static.*
client.api.v2.monitor.router.ipv4.*

🎯 API Coverage

FortiOS 7.6.5 - Schema v1.7.0:

Category	Endpoints	Description
CMDB	561	Configuration management
Monitor	490	Real-time monitoring data
Log	286	Log queries and management
Service	11	System services (sniffer, etc.)
Total	1,348	Complete API coverage

📖 Documentation

Getting Started

• Quick Start Guide - Installation and basic usage
• Authentication - API token setup
• Async Guide - Async/await patterns

User Guides

• Client Overview - FortiOSClient features
• Endpoint Methods - Using .get(), .post(), .put(), .delete()
• Response Objects - Working with API responses
• Error Handling - Exception handling

Advanced Topics

• Transactions - Multi-step operations
• Filtering & Queries - Advanced filtering
• Rate Limiting - Request throttling
• Validation - Input validation
• Debugging - Troubleshooting
• Singleton PUT Behavior - Important: Understanding FortiOS PUT semantics

API Reference

• Firewall Policies - Policy management
• Services - Service objects
• Schedules - Schedule objects
• Traffic Shapers - QoS configuration

⚠️ Important: FortiOS PUT Behavior

When using put() on singleton endpoints (like router.bgp), FortiOS uses merge semantics:

# ❌ This does NOT clear child tables!
fgt.api.cmdb.router.bgp.put(asn=65500)
# Neighbors, networks, etc. are UNCHANGED

# ✅ To clear child tables, explicitly pass empty arrays
fgt.api.cmdb.router.bgp.put(asn=65500, neighbor=[], network=[])

# ✅✅ BEST: Use child table helpers for granular operations
fgt.api.cmdb.router.bgp.neighbor.set(ip="10.1.1.1", remote_as=65001)
fgt.api.cmdb.router.bgp.neighbor.delete(ip="10.1.1.1")

See Singleton PUT Behavior for complete details.

✨ Advanced Features

Transaction Support

with client.transaction():
    # All operations in atomic transaction
    client.api.v2.cmdb.firewall.address.post(name="addr1", subnet="10.0.0.1/32")
    client.api.v2.cmdb.firewall.address.post(name="addr2", subnet="10.0.0.2/32")
    # Automatically committed on success, rolled back on error

Error Handling

from hfortix_core.exceptions import (
    ResourceNotFoundError,
    DuplicateEntryError,
    PermissionDeniedError
)

try:
    policy = client.api.v2.cmdb.firewall.policy.get(policyid=100)
except ResourceNotFoundError:
    print("Policy not found")
except PermissionDeniedError:
    print("Insufficient permissions")

Filtering & Querying

# Filter with operators (==, !=, =@, !@, <=, <, >=, >)
addresses = fgt.api.cmdb.firewall.address.get(
    filter="name=@web"  # Contains "web" (case insensitive)
)

# Multiple filters (AND logic)
addresses = fgt.api.cmdb.firewall.address.get(
    filter="name=@web&filter=subnet==10.1.1.0/24"
)

# Sort results
policies = fgt.api.cmdb.firewall.policy.get(
    sort="policyid,dsc"  # Descending order
)

# Pagination
addresses = fgt.api.cmdb.firewall.address.get(
    start=10,  # Start at index 10
    count=50   # Return 50 items
)

# Format - return specific fields only
policies = fgt.api.cmdb.firewall.policy.get(
    format="policyid|name|action"
)

# Combine all parameters
addresses = fgt.api.cmdb.firewall.address.get(
    filter="name=@test",
    sort="name,dsc",
    start=0,
    count=10,
    format="name|subnet|comment"
)

Note: Filtering, sorting, and formatting require FortiOS 6.4.2+

📋 Requirements

• Python 3.10 or higher
• FortiOS 7.0+ (tested with 7.6.5)
• Network access to FortiGate device

Dependencies

• hfortix-core - Core HTTP client (installed automatically)
• httpx >= 0.24.0
• pydantic >= 2.0.0

🔗 Related Packages

• hfortix-core - Core HTTP client
• hfortix - Meta-package for easy installation

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

💬 Support

• 🐛 Report Issues
• 💬 Discussions
• 📧 Email: [e-mail]

---

Author: Herman W. Jacobsen | LinkedIn | GitHub