Metadata-Version: 2.4
Name: hfortix-fortios
Version: 0.5.140
Summary: FortiOS SDK - Part of HFortix
Author-email: "Herman W. Jacobsen" <herman@wjacobsen.fo>
License: Proprietary
Project-URL: Homepage, https://github.com/hermanwjacobsen/hfortix
Project-URL: Repository, https://github.com/hermanwjacobsen/hfortix
Keywords: fortinet,fortigate,fortios,firewall,api,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: hfortix-core>=0.5.140
Requires-Dist: hfortix>=0.5.140
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: minimal

# HFortix FortiOS

Python SDK for FortiGate/FortiOS API - Complete, type-safe, production-ready.

[![PyPI version](https://badge.fury.io/py/hfortix-fortios.svg)](https://pypi.org/project/hfortix-fortios/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)


> **⚠️ BETA STATUS - Version 0.5.132 (January 21, 2026)**
>
> **Status:** Production-ready but in beta until v1.0 with comprehensive unit tests.

## Overview

Complete Python client for FortiOS 7.6.5 REST API with 100% endpoint coverage (1,348 endpoints), full type safety, and enterprise features. All code is auto-generated from FortiOS API schemas.

## Installation

```bash
pip install hfortix-fortios
```

This automatically installs:
- `hfortix-core` - Core utilities and HTTP client

**For everything (includes future products):**
```bash
pip install hfortix[all]
```

## Quick Start

```python
from hfortix_fortios import FortiOS

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

# Get system status (Monitor endpoint - GET)
status = fgt.api.monitor.system.status.get()
print(f"Hostname: {status.hostname}")
print(f"Version: {status.version}")

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

# Update an existing address (CMDB endpoint - PUT)
fgt.api.cmdb.firewall.address.put(
    name="web-server",
    subnet="192.168.1.101 255.255.255.255"
)

# Get a specific address (CMDB endpoint - GET)
addr = fgt.api.cmdb.firewall.address.get(name="web-server")
print(f"Address: {addr.name} = {addr.subnet}")

# Delete an address (CMDB endpoint - DELETE)
fgt.api.cmdb.firewall.address.delete(name="web-server")
```

## API Structure

All endpoints follow REST conventions with **GET**, **POST**, **PUT**, **DELETE** methods:

```python
# CMDB - Configuration Management (full CRUD)
fgt.api.cmdb.firewall.address.get()           # List all
fgt.api.cmdb.firewall.address.get(name="x")   # Get specific
fgt.api.cmdb.firewall.address.post(...)       # Create new
fgt.api.cmdb.firewall.address.put(...)        # Update existing
fgt.api.cmdb.firewall.address.delete(name="x") # Delete

# Monitor - Real-time data (mostly GET)
fgt.api.monitor.system.status.get()
fgt.api.monitor.system.resource.usage.get()
fgt.api.monitor.firewall.session.get()
fgt.api.monitor.router.ipv4.get()

# Log - Historical logs (GET)
fgt.api.log.disk.traffic.forward.get(rows=100)
fgt.api.log.disk.event.vpn.get(rows=50)
fgt.api.log.memory.event.system.get()

# Service - System services
fgt.api.service.sniffer.start.post(...)
```

## API Coverage

**FortiOS 7.6.5 - 100% Coverage (Schema v1.7.0):**

| Category | Endpoints | Description |
|----------|-----------|-------------|
| CMDB | 561 | Configuration management (firewall, system, VPN, routing, etc.) |
| Monitor | 490 | Real-time monitoring (sessions, stats, resources, etc.) |
| Log | 286 | Log queries (disk, memory, FortiAnalyzer, FortiCloud) |
| Service | 11 | Service operations (sniffer, security rating, system) |
| **Total** | **1,348** | With 2,129 implementation files |

## Key Features

### 🎯 IDE Autocomplete with Literal Types

Every enum parameter provides instant IDE suggestions:

```python
# ✨ Autocomplete for ALL enum fields
fgt.api.cmdb.firewall.policy.post(
    name="allow-web",
    srcintf=[{"name": "port1"}],
    dstintf=[{"name": "port2"}],
    srcaddr=[{"name": "all"}],
    dstaddr=[{"name": "web-server"}],
    service=[{"name": "HTTP"}, {"name": "HTTPS"}],
    action="accept",      # 💡 IDE: 'accept', 'deny', 'ipsec'
    status="enable",      # 💡 IDE: 'enable', 'disable'
    nat="enable",         # 💡 IDE: 'enable', 'disable'
    logtraffic="all",     # 💡 IDE: 'all', 'utm', 'disable'
    schedule="always"
)

# 🛡️ Type safety catches errors at development time
fgt.api.cmdb.system.interface.post(
    name="vlan100",
    vdom="root",
    mode="static",        # 💡 IDE: 'static', 'dhcp', 'pppoe'
    type="vlan",          # 💡 IDE: 'physical', 'vlan', 'tunnel', ...
    role="lan"            # 💡 IDE: 'lan', 'wan', 'dmz', 'undefined'
)
```

### 🎨 FortiObject Response Wrapper

All methods return `FortiObject` with clean attribute access:

```python
# Get policies and access fields directly
policies = fgt.api.cmdb.firewall.policy.get()

for policy in policies:
    print(f"Policy {policy.policyid}: {policy.name}")
    print(f"  Action: {policy.action}")
    print(f"  Status: {policy.status}")
    
    # join() flattens member tables for display
    print(f"  {policy.join('srcintf')} → {policy.join('dstintf')}")
    print(f"  {policy.join('srcaddr')} → {policy.join('dstaddr')}")

# Access as dict when needed
policy_dict = policy.to_dict()

# Access raw API envelope
raw = policy.raw  # {'http_status': 200, 'status': 'success', 'results': ...}
```

### ⚡ Async Support

```python
import asyncio
from hfortix_fortios import FortiOS

async def main():
    async with FortiOS(host="...", token="...", mode="async") as fgt:
        # All methods support await
        addresses = await fgt.api.cmdb.firewall.address.get()

        # Concurrent operations
        addr, pol, svc = await asyncio.gather(
            fgt.api.cmdb.firewall.address.get(),
            fgt.api.cmdb.firewall.policy.get(),
            fgt.api.cmdb.firewall.service.custom.get()
        )

asyncio.run(main())
```

### 🔧 Error Handling

```python
from hfortix_core import (
    APIError,
    ResourceNotFoundError,
    DuplicateEntryError,
    AuthenticationError,
)

try:
    fgt.api.cmdb.firewall.address.post(name="test", subnet="10.0.0.1/32")
except DuplicateEntryError:
    print("Address already exists")
except ResourceNotFoundError:
    print("Resource not found")
except AuthenticationError:
    print("Invalid API token")
except APIError as e:
    print(f"API Error: {e.message} (code: {e.error_code})")
```

### 🔒 Read-Only Mode & Operation Tracking

```python
# Safe testing - block all write operations
fgt = FortiOS(host="...", token="...", read_only=True)

# Audit logging - track all API calls
fgt = FortiOS(host="...", token="...", track_operations=True)
operations = fgt.get_operations()
```

### 🔍 Debugging

```python
# Enable debug logging
fgt = FortiOS(host="...", token="...", debug=True)

# Connection pool monitoring
stats = fgt.connection_stats
print(f"Active: {stats['active_requests']}/{stats['max_connections']}")

# Request inspection
result = fgt.api.cmdb.firewall.address.get()
info = fgt.last_request
print(f"Endpoint: {info['endpoint']}")
print(f"Response time: {info['response_time_ms']}ms")
```

### 🔧 Enterprise Features

- **Audit Logging**: Built-in compliance logging with SIEM integration
- **HTTP/2 Support**: Connection multiplexing for better performance
- **Automatic Retry**: Handles transient failures (429, 500, 502, 503, 504)
- **Circuit Breaker**: Prevents cascade failures with automatic recovery
- **Request Tracking**: Correlation IDs for distributed tracing

## Examples

### Firewall Policy Management

```python
# Create a policy
fgt.api.cmdb.firewall.policy.post(
    name="Allow-Web",
    srcintf=[{"name": "port1"}],
    dstintf=[{"name": "port2"}],
    srcaddr=[{"name": "all"}],
    dstaddr=[{"name": "web-servers"}],
    action="accept",
    schedule="always",
    service=[{"name": "HTTP"}, {"name": "HTTPS"}],
    logtraffic="all"
)

# Check if policy exists
if fgt.api.cmdb.firewall.policy.exists(policyid=10):
    # Update the policy
    fgt.api.cmdb.firewall.policy.put(
        policyid=10,
        status="disable"
    )
```

### Address Group Management

```python
# Create addresses
fgt.api.cmdb.firewall.address.post(
    name="subnet1",
    subnet="10.0.1.0 255.255.255.0"
)
fgt.api.cmdb.firewall.address.post(
    name="subnet2", 
    subnet="10.0.2.0 255.255.255.0"
)

# Create address group
fgt.api.cmdb.firewall.addrgrp.post(
    name="internal-networks",
    member=[{"name": "subnet1"}, {"name": "subnet2"}],
    comment="All internal networks"
)
```

### VPN Configuration

```python
# Create IPsec Phase 1
fgt.api.cmdb.vpn.ipsec.phase1_interface.post(
    name="site-to-site",
    type="static",
    interface="wan1",
    ike_version="2",
    peertype="any",
    proposal="aes256-sha256",
    remote_gw="203.0.113.10",
    psksecret="your-pre-shared-key"
)

# Create IPsec Phase 2
fgt.api.cmdb.vpn.ipsec.phase2_interface.post(
    name="site-to-site-p2",
    phase1name="site-to-site",
    proposal="aes256-sha256",
    src_subnet="10.0.0.0 255.0.0.0",
    dst_subnet="192.168.0.0 255.255.0.0"
)
```

### System Monitoring

```python
# Get system status
status = fgt.api.monitor.system.status.get()
print(f"FortiOS {status.version} build {status.build}")
print(f"Serial: {status.serial}")
print(f"Hostname: {status.hostname}")

# Get resource usage
resources = fgt.api.monitor.system.resource.usage.get()
print(f"CPU: {resources.results['cpu']}%")
print(f"Memory: {resources.results['mem']}%")

# Get active sessions
sessions = fgt.api.monitor.firewall.session.get()
print(f"Total sessions: {len(sessions.results)}")
```

### FortiManager Proxy

Route FortiOS API calls through FortiManager to managed devices:

```python
from hfortix_fortios import FortiManagerProxy

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

# Get a proxied FortiOS connection to a managed device
fgt = fmg.get_device("fw01")

# Use the same API as direct FortiOS!
addresses = fgt.api.cmdb.firewall.address.get()
for addr in addresses:
    print(f"{addr.name}: {addr.subnet}")

# Create, update, delete - all work through the proxy
fgt.api.cmdb.firewall.address.post(
    name="Server-01",
    subnet="10.0.1.10 255.255.255.255"
)

# Clean up
fmg.logout()
```

## Import Patterns

```python
# Recommended
from hfortix_fortios import FortiOS
from hfortix_fortios import FortiManagerProxy

# Also available
from hfortix import FortiOS
```

## Requirements

- Python 3.10+
- FortiOS 7.0+ (tested with 7.6.5)
- hfortix-core >= 0.5.132

## Documentation

- [Quick Start](https://github.com/hermanwjacobsen/hfortix/blob/main/QUICKSTART.md)
- [Async Guide](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/ASYNC_GUIDE.md)
- [API Reference](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/ENDPOINT_METHODS.md)
- [Filtering Guide](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/FILTERING_GUIDE.md)
- [Changelog](https://github.com/hermanwjacobsen/hfortix/blob/main/CHANGELOG.md)

## License

Proprietary - See LICENSE file

## Support

- 📖 [Documentation](https://github.com/hermanwjacobsen/hfortix)
- 🐛 [Report Issues](https://github.com/hermanwjacobsen/hfortix/issues)
- 💬 [Discussions](https://github.com/hermanwjacobsen/hfortix/discussions)

## Author

**Herman W. Jacobsen**
- Email: herman@wjacobsen.fo
- GitHub: [@hermanwjacobsen](https://github.com/hermanwjacobsen)
