hfortix 0.5.39

Python SDK for Fortinet products (FortiOS, FortiManager, FortiAnalyzer)

HFortix

Complete Python SDK for Fortinet Products - Modular, type-safe, production-ready.

⚠️ BETA STATUS - Version 0.5.32 (January 24, 2025)

Breaking Changes: v0.5.0 removes convenience wrappers. Use direct API access via fgt.api.* Status: Production-ready but in beta until v1.0 with comprehensive unit tests. What's New: Enhanced object mode with nested table wrapping and single object returns!

Version: 0.5.32 Status: Beta (100% auto-generated, production-ready, pending comprehensive unit tests for v1.0)

Overview

HFortix is a modular Python SDK that provides comprehensive, production-ready clients for Fortinet products. Starting with FortiOS/FortiGate, with future support planned for FortiManager, FortiAnalyzer, and more.

Version 0.5.32 features major improvements to object response mode, auto-normalization for list fields, and enhanced IDE support with 15,000+ parameters having enum autocomplete.

This is a meta-package that provides convenient installation patterns for the HFortix ecosystem.

Installation

Minimal Installation (Core Only)

pip install hfortix

Installs only hfortix-core - the shared foundation (exceptions, HTTP client, type definitions).

FortiOS/FortiGate Support

pip install hfortix[fortios]

Installs hfortix-core + hfortix-fortios - Everything needed for FortiGate/FortiOS.

Complete Installation

pip install hfortix[all]

Installs all current and future Fortinet product packages.

Individual Packages

You can also install product packages directly:

# Just FortiOS (includes core automatically)
pip install hfortix-fortios

# Just the core framework
pip install hfortix-core

Quick Start

FortiOS/FortiGate

from hfortix_fortios import FortiOS

# Connect to FortiGate
fgt = FortiOS(
    host="192.168.1.99",
    token="your-api-token",
    verify=False
)

# Get system status
status = fgt.monitor.system.status()
print(f"Hostname: {status['hostname']}")

# Manage firewall addresses
fgt.api.cmdb.firewall.address.create(
    name="web-server",
    subnet="192.168.1.100 255.255.255.255"
)

# Use convenience wrappers
fgt.firewall.service_custom.create(
    name="HTTPS-8443",
    tcp_portrange="8443",
    protocol="TCP/UDP/SCTP"
)

Package Structure

HFortix uses a modular architecture:

hfortix (meta-package)
├── hfortix-core          # Shared foundation
│   ├── Exception system (387+ error codes)
│   ├── HTTP client framework
│   ├── Type definitions
│   └── Common utilities
│
└── hfortix-fortios       # FortiOS/FortiGate client
    ├── Complete API coverage (750+ endpoints)
    ├── Convenience wrappers
    ├── Auto-generated validators
    └── Product-specific features

Future Packages:

• hfortix-fortimanager - FortiManager API client
• hfortix-fortianalyzer - FortiAnalyzer API client
• hfortix-fortiswitch - FortiSwitch API client
• And more...

Key Features

🎯 Modular Design

Install only what you need:

• Minimal footprint with hfortix-core
• Product-specific packages when needed
• Shared infrastructure across all products

⚡ Complete FortiOS Support

API Coverage (FortiOS 7.6.5):

• 1,219 total endpoints (100% auto-generated)
• 886 CMDB endpoints (configuration)
• 295 Monitor endpoints (real-time data)
• 38 Log endpoints (query logs from disk, memory, FortiAnalyzer, FortiCloud)

Features:

• Complete .pyi type stubs for perfect IDE autocomplete
• Schema-based validation for all parameters
• Auto-generated tests for all endpoints
• Swagger fallback for 100% coverage

�� Enterprise Features

• Async/Await Support: Full async implementation with context managers
• Error Handling: 387+ specific error codes with comprehensive exception hierarchy
• HTTP/2 Support: Connection multiplexing for better performance
• Automatic Retry: Handles transient failures intelligently
• Circuit Breaker: Prevents cascade failures with automatic recovery
• Type Safety: Full type hints with IDE autocomplete
• Read-Only Mode: Safe testing without accidental changes
• Operation Tracking: Audit logging for all API calls
• Performance Testing: Built-in tools to optimize device communication

Import Patterns

Recommended (New in v0.4.0-dev1)

# Product packages
from hfortix_fortios import FortiOS

# Core exceptions
from hfortix_core import (
    APIError,
    ResourceNotFoundError,
    DuplicateEntryError
)

Legacy (Still Supported)

from hfortix import FortiOS
from hfortix.FortiOS import FortiOS

Migration from v0.4.x

Breaking Changes in v0.5.0:

• All convenience wrappers have been removed
• Use direct API access via fgt.api.cmdb.*, fgt.api.monitor.*, fgt.api.log.*

Old (v0.4.x):

from hfortix_fortios.firewall import FirewallAddress
addr = FirewallAddress(fgt)
result = addr.create(name="test", subnet="10.0.0.1/32")

New (v0.5.0):

result = fgt.api.cmdb.firewall.address.create(
    name="test",
    subnet="10.0.0.1/32"
)

All methods work the same - just accessed directly through the endpoint.

Documentation

Getting Started:

• Quick Start Guide - Installation and basic usage
• Async Guide - Async/await patterns
• API Reference - Complete method reference

Convenience Wrappers:

• Overview - All wrappers
• Service Management
• Schedules
• Traffic Shaping

Advanced Topics:

• Validation Guide - Using validators
• Error Handling - Exception system
• Performance Testing - Optimization

Project Info:

• Changelog - Version history
• GitHub Repository - Complete docs

Requirements

• Python 3.10+
• FortiOS 7.0+ (tested with 7.6.5)

Development Status

Beta - All APIs are functional and tested against live Fortinet devices. The package remains in beta status until version 1.0.0 with comprehensive unit test coverage.

Current Test Coverage:

• 226 test files for FortiOS
• 75%+ pass rate
• ~50% of endpoints have dedicated tests
• All implementations validated against FortiOS 7.6.5

Why Modular?

Benefits of the split package architecture:

1. Smaller Dependencies: Install only what you need
2. Faster Updates: Product packages can be updated independently
3. Better Organization: Clear separation of concerns
4. Easier Maintenance: Focused development per product
5. Future Flexibility: Easy to add new Fortinet products

Version History

• v0.4.0-dev1 (Current): Package split - modular architecture
• v0.3.39: Convenience wrappers (services, schedules, shaping, IP/MAC binding)
• v0.3.38: Firewall policy wrapper with 150+ parameters
• v0.3.x: Async support, error handling, performance tools
• v0.1.x-v0.2.x: Initial FortiOS API implementation

License

Proprietary - See LICENSE file

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

Author

Herman W. Jacobsen

• Email: [e-mail]
• LinkedIn: linkedin.com/in/hermanwjacobsen
• GitHub: @hermanwjacobsen