Skip to content

🚀 Python IPAM - Features & Roadmap

Version: 1.1.0 Last Updated: 2026-11-02

Lease retirement API (2026-11-02)

Implemented POST /api/v1/hosts/{id}/retire-lease: source ownership, expiry, configurable server grace and curation guards with an atomic full-snapshot comparison. Renewals/manual edits return 412 instead of deleting changed data. Collector-side complete-snapshot selection and recurring execution remain separate. See API contract.

📊 Project Status Overview

Category Completed In Progress Planned Total
Core Features 9 0 3 12
API Integration 2 0 0 2
UI/UX 8 0 2 10
Data Management 5 0 9 14
Testing 6 0 1 7
Security 0 0 2 2

✅ Completed Features

Core IPAM Functionality

  • [IPAM-001] ✅ Network Management
  • Priority: Critical | Category: Core
  • Description: Create, view, and manage IP networks with CIDR notation

  • Acceptance Criteria:

    • ✅ Add networks with CIDR validation
    • ✅ Automatic broadcast address calculation
    • ✅ VLAN ID support
    • ✅ Location and description fields
    • ✅ Network utilization statistics

  • [IPAM-002] ✅ Host Management

  • Priority: Critical | Category: Core
  • Description: Manage individual IP addresses and hosts
  • Acceptance Criteria:
    • ✅ Add hosts with IP validation
    • ✅ Hostname and MAC address tracking
    • ✅ Status management (active/inactive/reserved)
    • ✅ Assignment tracking (is_assigned)
    • ✅ Discovery metadata (last_seen, discovery_source)
    • ✅ Sortable Last Seen timestamp in the Hosts table
    • ✅ Auto-network detection for hosts
    • ✅ Host-to-network relationships
    • ✅ DHCP range management per network

Data Management

  • [IPAM-003] ✅ Extensible Export System
  • Priority: High | Category: Data Management
  • Description: Plugin-based export system supporting multiple formats

  • Acceptance Criteria:

    • ✅ CSV export for networks and hosts
    • ✅ JSON export format
    • ✅ Abstract base class for exporters
    • ✅ Factory pattern for format selection
    • ✅ Legacy route compatibility

  • [IPAM-004] ✅ Extensible Import System

  • Priority: High | Category: Data Management
  • Description: Plugin-based import system with validation

  • Acceptance Criteria:

    • ✅ CSV and JSON import with validation
    • ✅ Optional network names and domains in CSV and JSON imports
    • ✅ Error handling and reporting
    • ✅ Duplicate detection and skipping
    • ✅ Optional updates of existing networks with CIDR change protection
    • ✅ Optional host updates by IP address, preserving omitted fields
    • ✅ Strip matching network domain suffixes from imported hostnames
    • ✅ Network address normalization before duplicate detection and saving
    • ✅ Abstract base class for importers
    • ✅ Format auto-detection by extension

  • [IPAM-017] ✅ Data Backup & Restore

  • Priority: Medium | Category: Data Management
  • Description: Backup and restore utilities with verification
  • GitHub Issue: #12 (closed)
  • Acceptance Criteria:
    • ✅ Scheduled backups via CLI (cron-friendly)
    • ✅ One-click restore from backup
    • ✅ Backup verification and integrity checks
    • ✅ Database migration utilities via Flask-Migrate

UI/UX

  • [IPAM-005] ✅ Responsive Web Interface
  • Priority: High | Category: UI/UX
  • Description: Modern Bootstrap 5 interface with DataTables

  • Acceptance Criteria:

    • ✅ Bootstrap 5 responsive design
    • ✅ DataTables for sorting/filtering
    • ✅ Navigation with dropdown menus
    • ✅ Flash message system
    • ✅ Mobile-friendly interface

  • [IPAM-006] ✅ Dashboard with Statistics

  • Priority: Medium | Category: UI/UX
  • Description: Overview dashboard with network utilization
  • Acceptance Criteria:
    • ✅ Network and host count cards
    • ✅ Utilization progress bars
    • ✅ Recent networks/hosts tables
    • ✅ Visual status indicators

Development & Testing

  • [IPAM-007] ✅ Comprehensive Test Suite
  • Priority: High | Category: Testing
  • Description: Unit and integration tests with coverage

  • Acceptance Criteria:

    • ✅ Model tests for Network/Host
    • ✅ Route tests for all endpoints
    • ✅ Form validation tests
    • ✅ Export/Import functionality tests
    • ✅ Test fixtures and factories

  • [IPAM-008] ✅ Code Quality Standards

  • Priority: High | Category: Development
  • Description: Google Style Guide compliance and tooling
  • Acceptance Criteria:
    • ✅ Ruff formatting (80 char limit)
    • ✅ Google-style imports and structure
    • ✅ Ruff linting compliance
    • ✅ Git hooks and standards

🔄 In Progress

No features currently in progress

✅ Recently Completed

Core Features Enhancement

  • [IPAM-020] ✅ Network Names and Domains
  • Priority: Medium | Category: Core
  • Status: Complete
  • Description: Add name and domain fields to networks for better organization
  • Acceptance Criteria:
    • ✅ Add name field to Network model (optional, user-friendly identifier)
    • ✅ Add domain field to Network model (optional, DNS domain for network)
    • ✅ Update network forms to include new fields
    • ✅ Update network displays and tables
    • ✅ Database migration for existing networks

  • Technical Implementation:

    • Added name and domain VARCHAR(100) columns to networks table
    • Updated NetworkForm with new optional fields
    • Enhanced all network templates and API responses
    • Backward compatible with existing networks

  • [IPAM-021] ✅ Host CNAME Support

  • Priority: Medium | Category: Core
  • Status: Complete
  • Description: Add CNAME alias support for hosts with export integration
  • Acceptance Criteria:
    • ✅ Add cname field to Host model (optional, DNS alias)
    • ✅ Update host forms and displays
    • ✅ Extend DNSmasq exporter with cname=CNAME,HOSTNAME entries
    • ✅ Update all templates to show CNAME field
    • ✅ CNAME statistics in DNSmasq export

  • Technical Features:

    • Added cname VARCHAR(255) column to hosts table
    • Updated HostForm and all host templates
    • Enhanced DNSmasq exporter with separate CNAME section
    • CNAME aliases work with all DNSmasq modes (DNS/DHCP/Combined)
    • Export format: cname=ALIAS,HOSTNAME

  • [IPAM-022] ✅ Form Field Validation Indicators

  • Priority: Low | Category: UI/UX
  • Status: Complete
  • Description: Visual indicators for mandatory vs optional form fields
  • Acceptance Criteria:
    • ✅ Add asterisk (*) to required field labels
    • ✅ Helpful form-text for all fields (required/optional)
    • ✅ Consistent styling across all forms
    • ✅ Clear visual distinction between mandatory and optional fields
  • UI Improvements:
    • Red asterisk (*) for required fields (Network Address, CIDR, IP Address)
    • Form-text descriptions for all fields
    • Consistent Bootstrap styling throughout forms

CRUD Operations

  • [IPAM-019] ✅ Edit and Delete Functionality for Networks and Hosts
  • Priority: High | Category: Core
  • Status: Complete
  • Description: Full CRUD operations with edit forms and safe deletion
  • Acceptance Criteria:
    • ✅ Edit network form with validation and error handling
    • ✅ Edit host form with network auto-detection and manual assignment
    • ✅ Delete network with host-dependency protection
    • ✅ Delete host with confirmation dialog
    • ✅ Action buttons integrated into DataTables
    • ✅ JavaScript confirmation dialogs for deletions
    • ✅ Flash messages for success/error feedback
    • ✅ Form pre-population with existing data
  • Routes Added:
    • GET/POST /edit_network/<id> - Edit network form
    • GET/POST /edit_host/<id> - Edit host form
    • POST /delete_network/<id> - Delete network (with host check)
    • POST /delete_host/<id> - Delete host

  • Technical Features:

    • Network deletion blocked if hosts are assigned
    • Host IP validation and network auto-detection
    • CSRF protection for all forms
    • Bootstrap form styling with validation feedback
    • JavaScript confirmation with host count display

  • [IPAM-033] ✅ Detail Views for Networks and Hosts

  • Priority: Medium | Category: UI/UX
  • Status: Complete
  • Description: Read-only detail pages so objects can be inspected without opening the edit form
  • Acceptance Criteria:
    • ✅ Network detail: properties, utilization, DHCP ranges, host table
    • ✅ Host detail: properties, FQDN, network link, allocation/lease/last seen
    • ✅ Network/IP columns in lists and dashboard link to the detail pages
    • ✅ Edit and Delete actions available on the detail pages
    • ✅ Saving or cancelling an edit form returns to the detail page

  • Routes Added:

    • GET /networks/<id> - Network detail
    • GET /hosts/<id> - Host detail

  • [IPAM-028] ✅ Visual Subnet Display

  • Priority: Medium | Category: Network Tools / UI
  • Status: Complete
  • GitHub Issue: #85
  • Description: Address map on the network detail view showing each address's recorded state instead of only an aggregate percentage
  • Acceptance Criteria:
    • ✅ Grid of addresses colour-coded by derived allocation state: reserved/static, dynamic, recorded but unconfirmed, DHCP pool, no recorded allocation, network/broadcast
    • ✅ Hover shows IP, allocation state, hostname, MAC and description; click opens the host, or Add Host prefilled for unrecorded addresses
    • ✅ Large subnets: one /24 block at a time with previous/next and jump-to-IP; clickable block occupancy overview up to /16
    • ✅ Available on the network detail view; 16 columns on narrow, 32 on wide screens

  • Technical Notes:

    • ipam/subnet_map.py builds the map from stored data only; an unrecorded address is not shown as confirmed free
    • Gateways are not modelled yet, so they appear as normal hosts
    • Block overview is computed arithmetically, not per address

  • [IPAM-034] ✅ Guarded Reservation Removal and Conversion

  • Priority: Medium | Category: Data Management / API
  • Status: Complete (IPAM side; collector switch pending)
  • GitHub Issue: #106
  • Design: ADDRESS_ASSIGNMENT_MODEL.md
  • Description: POST /api/v1/hosts/{id}/release-reservation deletes a reservation removed at its source, or converts it to a dynamic record backed by its current lease, analogous to retire-lease
  • Acceptance Criteria:
    • ✅ Conditional delete with a full expected snapshot (412 on any change, one atomic statement); refused while the stored lease is valid
    • ✅ Atomic reservation → dynamic conversion in one request (replaces the collector's two upserts with the udm-reservation-release marker)
    • ✅ Only reservations owned by source; static/dynamic/foreign refused
    • ✅ Manual DELETE unchanged
    • ✅ Documented in API.md
  • Follow-up: Switch the homelab-automation collector to the endpoint

Export/Import System

  • [IPAM-018] ✅ DNSmasq Host Export with Multiple Modes
  • Priority: Medium | Category: Export
  • Status: Complete
  • Description: Export hosts in DNSmasq configuration format with configurable modes
  • Acceptance Criteria:
    • ✅ DNS Mode: Only host-record=hostname,IP entries for DNS server use
    • ✅ DHCP Mode: Only dhcp-host=MAC,IP,hostname entries for DHCP server use
    • ✅ Combined Mode: Both DNS and DHCP entries for full DNSmasq setup
    • ✅ Separate active and reserved hosts in all modes
    • ✅ Include mode-specific statistics and comments
    • ✅ Skip inactive hosts and hosts without hostnames
    • ✅ Skip hosts without MAC addresses in DHCP-only mode
  • Export Routes:
    • /export/hosts/dnsmasq - Combined mode (default)
    • /export/hosts/dnsmasq-dns - DNS-only mode
    • /export/hosts/dnsmasq-dhcp - DHCP-only mode
  • Technical Notes:
    • DNS Mode: All hosts get host-record=hostname,IP (ignores MAC)
    • DHCP Mode: Only hosts with MAC get dhcp-host=MAC,IP,hostname
    • Combined Mode: MAC hosts get dhcp-host, non-MAC hosts get host-record
    • File extension: .conf
    • MIME type: text/plain
    • Configurable via DNSmasqExporter constructor

Testing

  • [IPAM-009] ✅ Export/Import Test Coverage
  • Priority: High | Category: Testing
  • Status: Complete
  • Description: Complete test coverage for new export/import system
  • Acceptance Criteria:
    • ✅ CSV exporter/importer tests
    • ✅ JSON exporter/importer tests
    • ✅ Route integration tests
    • ✅ Error handling edge cases
    • ✅ Performance tests for large datasets
  • Completed: Added comprehensive edge case tests, performance tests, and JSON import functionality

API & Integration

  • [IPAM-023] ✅ Comprehensive REST API with OpenAPI/Swagger
  • Priority: High | Category: API
  • Status: Complete
  • Description: Complete RESTful API for all IPAM operations with filtering, pagination, and interactive Swagger UI documentation
  • Acceptance Criteria:
    • Network Operations:
    • ✅ GET /api/v1/networks - List all networks (with filtering support)
    • ✅ GET /api/v1/networks/{id} - Get specific network details
    • ✅ POST /api/v1/networks - Create new network
    • ✅ PUT /api/v1/networks/{id} - Update existing network
    • ✅ POST /api/v1/networks/upsert - Create-or-update by network address
    • ✅ DELETE /api/v1/networks/{id} - Delete network (with host check)
    • ✅ GET /api/v1/networks/{id}/hosts - List hosts in specific network
    • Host Operations:
    • ✅ GET /api/v1/hosts - List all hosts (with filtering support)
    • ✅ GET /api/v1/hosts/{id} - Get specific host details
    • ✅ POST /api/v1/hosts - Create new host
    • ✅ PUT /api/v1/hosts/{id} - Update existing host
    • ✅ POST /api/v1/hosts/upsert - Create-or-update by IP address
    • ✅ DELETE /api/v1/hosts/{id} - Delete host
    • DHCP Range Operations:
    • ✅ POST /api/v1/dhcp-ranges/upsert - Create-or-update by network + start IP
    • Data Consistency:
    • ✅ Network address normalization (any host IP in the network normalizes to its base address) applied consistently across POST/PUT/upsert, the web UI, and import
    • ✅ Matching network domain suffixes stripped from hostnames, applied consistently across POST/PUT/upsert, the web UI, and import
    • ✅ CIDR-change protection on network updates, applied consistently across PUT/upsert, the web UI, and import
    • ✅ Network overlap rejection (create and update), applied consistently across POST/PUT/upsert, the web UI, and import; no nested/hierarchical subnets (see IPAM-010)
    • IP Management:
    • ✅ GET /api/v1/ip/networks/{id}/next-ip - Get next available IP in network
    • ✅ GET /api/v1/ip/networks/{id}/available-ips - List all available IPs
    • ✅ GET /api/v1/ip/{ip_address} - Query IP address status/details
    • Filtering & Search:
    • ✅ Network filters: name, domain, vlan_id, location
    • ✅ Host filters: hostname, cname, status, mac_address, network_id
    • ✅ Pagination support: page, per_page
    • Response Format:
    • ✅ Consistent JSON responses with metadata
    • ✅ Error handling with proper HTTP status codes
    • ✅ Interactive Swagger UI at /api/v1/docs
  • Technical Implementation:
    • Flask-RESTX for auto-documentation and Swagger UI
    • Application Factory pattern for modular architecture
    • SQLAlchemy models in dedicated ipam/models.py
    • Comprehensive error handling with proper status codes
    • Blueprint-based routing (ipam/api/ and ipam/web/)
  • Implementation Files:
    • ipam/__init__.py - Application factory with db initialization
    • ipam/extensions.py - Flask-SQLAlchemy extension
    • ipam/models.py - Network and Host models
    • ipam/config.py - Configuration with absolute database paths
    • ipam/api/__init__.py - API blueprint and Swagger configuration
    • ipam/api/models.py - Request/response serialization models
    • ipam/api/networks.py - Network CRUD endpoints
    • ipam/api/hosts.py - Host CRUD endpoints
    • ipam/api/ip_management.py - IP allocation and query endpoints
    • ipam/web/ - Web interface blueprint
    • API.md - Complete API documentation
    • tests/test_database.py - Database initialization tests
  • Completed: API fully operational at http://127.0.0.1:5000/api/v1 with Swagger UI at /api/v1/docs

  • Notes: API authentication and rate limiting are now supported.

  • [IPAM-014] ✅ REST API Expansion (Auth + Rate Limiting)

  • Priority: Medium | Category: API
  • Status: Complete
  • GitHub Issue: #9 (closed)
  • Description: Token authentication and rate limiting for all API endpoints

  • Acceptance Criteria:

    • ✅ Token-based authentication via Authorization: Bearer or X-API-Key
    • ✅ Swagger UI remains publicly accessible
    • ✅ Configurable rate limit defaults and limiter backend
    • ✅ Environment-driven configuration (API_TOKENS, API_RATE_LIMIT)
    • ✅ Optional rate limiting toggle (RATELIMIT_ENABLED)

  • [IPAM-032] ✅ Address Assignment, Leases and Observations

  • Priority: High | Category: Core / API
  • Status: Complete (IPAM side, phase 1)
  • Design: ADDRESS_ASSIGNMENT_MODEL.md
  • Description: Track how an address is assigned (reservation, static, dynamic, unknown), explicitly observed DHCP leases and device observations as independent aspects with per-aspect provenance, instead of overloading status
  • Acceptance Criteria:
    • ✅ Additive nullable fields via Alembic migration; existing data preserved, UDM reservation rows backfilled to reservation
    • ✅ Derived allocation_state (never stored)
    • ✅ Upsert reconciliation: per-aspect partial updates, older timestamps ignored, persistent assignments not downgraded by leases, MAC changes on reservations/static need confirmation (409)
    • ✅ Timezone-aware UTC timestamps in the API
    • ✅ Next IP, available IPs and network counters share one rule
    • ✅ Web UI (assignment selector, allocation column and details), JSON/CSV export and import
  • Follow-ups: [IPAM-034], [IPAM-035], [IPAM-036]; collector-side status and open items in ADDRESS_ASSIGNMENT_MODEL.md

📋 Planned Features

Network Tools

  • [IPAM-010] 📅 Subnet Calculator
  • Priority: Medium | Category: Network Tools
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #5
  • Description: Built-in subnet calculator and IP range tools
  • Acceptance Criteria:
    • Calculate available subnets from larger networks
    • Visual subnet splitting recommendations
    • IP range conflict detection
    • Subnet mask conversion tools

  • Technical Notes:

    • Use ipaddress library for calculations
    • Add JavaScript for real-time calculations

  • [IPAM-011] 📅 Network Scanner Integration

  • Priority: Medium | Category: Discovery
  • Estimated Effort: High (4-5 days)
  • GitHub Issue: #6
  • Description: Scan network ranges for active hosts
  • Acceptance Criteria:
    • Ping sweep functionality
    • Port scanning for common services
    • Auto-populate discovered hosts
    • Scheduled scan capabilities
  • Dependencies: [IPAM-010] for subnet calculations
  • Technical Notes: Consider using python-nmap library

Network Management

  • [IPAM-029] 📅 Locations Management
  • Priority: Medium | Category: Data Management
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #86
  • Description: Dedicated Location entity (CRUD) instead of the current free-text location field on Network

  • Acceptance Criteria:

    • Location model/table (name, optional description/address)
    • CRUD UI for locations (list, add, edit, delete)
    • Network form uses a Location dropdown instead of free text, with migration path for existing values
    • Filter networks/hosts by location
    • REST API endpoints for locations

  • [IPAM-030] 📅 VLAN Management

  • Priority: Medium | Category: Data Management
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #87
  • Description: Dedicated VLAN entity (CRUD) instead of the current raw vlan_id integer field on Network
  • Acceptance Criteria:
    • VLAN model/table (VLAN ID, name, description)
    • CRUD UI for VLANs (list, add, edit, delete)
    • Network form uses a VLAN dropdown/selector instead of a raw integer field
    • Validation to prevent duplicate/conflicting VLAN IDs
    • Filter networks/hosts by VLAN
    • REST API endpoints for VLANs

Data Management

  • [IPAM-024] 📅 IP Lease History
  • Priority: Medium | Category: Data Management
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #88
  • Description: Track assignment and metadata changes for hosts and networks

  • Acceptance Criteria:

    • Record create/update/delete events with timestamp and actor
    • Persist history entries in a dedicated table
    • UI for viewing history on host and network details
    • API endpoints for history retrieval
    • Export history entries in CSV/JSON

  • [IPAM-012] 📅 Advanced Import Formats

  • Priority: Low | Category: Data Management
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #7
  • Description: Support for XML, Excel, and network tool exports
  • Acceptance Criteria:
    • XML import/export
    • Excel (.xlsx) support
    • Nmap XML import
    • Cisco/HP switch MAC table import

  • Dependencies: [IPAM-004] plugin system

  • [IPAM-013] 📅 Advanced Export with Filtering

  • Priority: High | Category: Data Management
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #8
  • Description: Export all data or filtered subsets with advanced options
  • Acceptance Criteria:
    • Complete Database Export: All networks, hosts, and relationships
    • Filtered Network Export: By VLAN, location, IP range, utilization
    • Filtered Host Export: By status, network, hostname pattern, date range
    • Multiple Format Support: CSV, JSON, Excel for all export types
    • Custom Field Selection: Choose which columns to include
    • Export Templates: Save and reuse filter configurations
  • UI Features:
    • Advanced filter interface with multiple criteria
    • Export preview with row count estimation
    • Progress indicator for large exports
    • Download history and re-export capability
  • Technical Implementation: 
    # Export with advanced filtering
/export/networks?vlan_id=100&location=datacenter&format=csv
/export/hosts?status=active&network_id=5&format=json
/export/complete?include=networks,hosts,relationships&format=excel

# Filter examples
networks: VLAN ID, location, IP range, utilization %, description
hosts: status, network, hostname regex, IP range, last_seen date
  • UI Mockup: 
    [ Advanced Export ]

Export Type: [●] Networks [ ] Hosts [●] Complete Database

Filters:
┌─ Networks ─────────────────────────────────────────┐
│ VLAN ID: [100,200-300] Location: [datacenter*]     │
│ IP Range: [10.0.0.0/8] Utilization: [>80%]        │
└────────────────────────────────────────────────────┘

┌─ Hosts ────────────────────────────────────────────┐
│ Status: [☑active ☐inactive ☑reserved]             │
│ Hostname: [server*] Last Seen: [last 30 days]     │
└────────────────────────────────────────────────────┘

Format: [CSV ▼] Include: [☑IP ☑Hostname ☐MAC ☑Status]

Preview: ~1,247 networks, ~5,632 hosts
[Export] [Save as Template] [Load Template]

  • Dependencies: [IPAM-004] plugin system for format support

  • [IPAM-027] 📅 Custom Fields

  • Priority: Medium | Category: Data Management
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #89
  • Description: User-defined fields for hosts and networks

  • Acceptance Criteria:

    • Admin UI to define custom fields (string/int/bool/date)
    • API support for reading and writing custom fields
    • Export/import includes custom field values
    • Validation for required fields and type constraints

  • [IPAM-031] 📅 CMDB Sync Exporter

  • Priority: Medium | Category: Data Management
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #92
  • Description: Exporter that pushes eligible hosts to the Simple CMDB's /api/server/upsert endpoint, so IP allocations for devices not covered by other CMDB data sources (Ansible, inventory_collector) show up as CMDB assets
  • Acceptance Criteria:
    • Add a device_type field to the Host model (server, network, storage, vip, printer, iot, client, infra), with migration and form/API updates
    • New exporter module in ipam/exporters/ targeting the CMDB /api/server/upsert endpoint
    • Sync filter: device_type == "server" AND is_assigned AND hostname is set
    • Configurable CMDB base URL and API token via environment variables
    • Dry-run/preview mode before writing
    • Outgoing payload tagged with a distinct owner (e.g. ipam) for traceability; note that the CMDB has no field-level conflict resolution, so this sync must run before the Ansible cmdb_report role (by convention/schedule) if Ansible-reported data should not be overwritten

  • Dependencies: Builds on the existing exporter plugin system (IPAM-003)

  • [IPAM-016] 📅 Local User Management UI

  • Priority: Medium | Category: UI/Security
  • Estimated Effort: Small (1-2 days)
  • GitHub Issue: #11
  • Description: Admin interface for local user management
  • Acceptance Criteria:
    • User list with search and filtering
    • Add/edit/disable user accounts
    • Role assignment interface
    • Password reset functionality
    • User activity logging
  • Dependencies: [IPAM-015] hybrid authentication system

  • Technical Notes:

    • Reuse existing Bootstrap/DataTables UI patterns
    • Add password strength validation
    • Implement user audit trail

  • [IPAM-035] 📅 Source Identity and Scoped Retirement

  • Priority: Low | Category: Data Management
  • Estimated Effort: High (4-5 days)
  • GitHub Issue: #107
  • Design: ADDRESS_ASSIGNMENT_MODEL.md
  • Description: External identifiers and source scopes for hosts, networks and DHCP ranges, so records that disappear from a source can be retired safely without assuming a single authoritative source
  • Acceptance Criteria:
    • Nullable external identifier and source scope on hosts, networks and DHCP ranges (Alembic migration, API/upsert support)
    • Bookkeeping of complete successful snapshots per source/scope
    • Retirement of networks and DHCP ranges only after a complete snapshot of their owning scope; failed or partial collection retires nothing
    • Field ownership rules defined before enabling retirement
  • Dependencies: [IPAM-032], [IPAM-034]

  • Technical Notes: Needed once more than one site or reservation source feeds the same IPAM; today the collector treats the single UDM as sole reservation authority

  • [IPAM-036] 📅 Multiple Claims per Assignment Aspect

  • Priority: Low | Category: Data Management
  • Estimated Effort: High (4-5 days)
  • GitHub Issue: #108
  • Design: ADDRESS_ASSIGNMENT_MODEL.md
  • Description: Child records keyed by source/external identity so several collectors can claim the same aspect (assignment, lease, observation) instead of last-writer-wins on flat fields
  • Acceptance Criteria:
    • Precedence and conflict rules defined and documented first
    • Conflicting MAC claims remain visible in API and UI
    • Derived allocation state computed from all claims
    • Existing flat fields stay readable for legacy clients
  • Dependencies: [IPAM-035]
  • Technical Notes: Only worthwhile once a second collector claims the same aspect

Core Validation

  • [IPAM-026] 📅 IP Conflict Detection
  • Priority: Medium | Category: Core
  • Estimated Effort: Medium (2-3 days)
  • GitHub Issue: #90
  • Description: Detect duplicate IPs and overlapping ranges
  • Acceptance Criteria:
    • ✅ Detect duplicate IPs within a network (DB-level unique constraint on Host.ip_address)
    • ✅ Detect overlapping networks and DHCP range overlaps (Network.find_overlapping, enforced in web UI and API)
    • ✅ UI warnings on create/update (flash messages on overlap)
    • API returns structured conflict errors (currently a plain message string)
    • Background validation for existing data (conflicts introduced before these checks existed, e.g. via direct DB edits)

Security & Authentication

  • [IPAM-025] 📅 Role-Based Access Control
  • Priority: High | Category: Security
  • Estimated Effort: Medium (3-4 days)
  • GitHub Issue: #91
  • Description: Fine-grained permissions across UI and API

  • Acceptance Criteria:

    • Roles: ReadOnly, Editor, Admin, APIOnly
    • Enforce permissions on UI routes and API endpoints
    • Admin UI for role assignment
    • Configurable default role for new users
    • Audit log entries for role changes

  • [IPAM-015] 📅 Hybrid Authentication System

  • Priority: High | Category: Security
  • Estimated Effort: Medium (3-4 days), +1-2 days for LDAP
  • GitHub Issue: #10
  • Description: Support local user management, OIDC via OAuth2 Proxy, and direct LDAP/Active Directory authentication
  • Acceptance Criteria:
    • Local Authentication: Built-in user registration, login, password reset
    • OAuth2 Proxy Support: OIDC integration via reverse proxy
    • Forward Auth Support: Accept the authenticated user from a forward-auth proxy (e.g. Authelia with Traefik/nginx/Caddy) via the Remote-User header, optionally groups via Remote-Groups for role mapping; header names configurable
    • Trusted Proxy Only: Identity headers are honoured only from configured trusted proxy addresses; requests that bypass the proxy must not be able to spoof Remote-User
    • API Unaffected: /api/v1/ keeps token authentication and must be excluded from forward auth so collectors keep working
    • LDAP Authentication: Direct bind against an LDAP/Active Directory server (configurable server URL, bind DN, user/group search base), with group-to-role mapping
    • Role-based Access Control: Admin, User, ReadOnly roles
    • Configurable Auth Mode: Environment variable to switch between modes
    • User Management UI: Admin interface for local users
    • Session Management: Secure session handling across all modes
  • Technical Notes:
    • Use Flask-Login for local authentication
    • Header extraction for proxy-based auth (OAuth2 Proxy X-Forwarded-User, forward auth Remote-User/Remote-Groups)
    • Forward auth is the low-effort first step: the proxy already runs in front of the deployment, and the app only maps the header to a user/role (no password storage)
    • python-ldap or ldap3 for direct LDAP/Active Directory binds
    • Unified User model supporting all three auth types
    • Role inheritance from OIDC groups, LDAP groups, or local assignment

  • Authentication Modes:

    Mode 1: Local Authentication (Default) 

    # .env
AUTH_MODE=local
SECRET_KEY=your-secret-key

    Mode 2: OAuth2 Proxy 

    # docker-compose.auth.yml
services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:latest
    ports: ["4180:4180"]
    environment:
      - OAUTH2_PROXY_UPSTREAM=http://ipam:5000
      - OAUTH2_PROXY_OIDC_ISSUER_URL=${OIDC_ISSUER}
      - OAUTH2_PROXY_CLIENT_ID=${OIDC_CLIENT_ID}
      - OAUTH2_PROXY_PASS_USER_HEADERS=true
  ipam:
    environment:
      - AUTH_MODE=proxy
      - AUTH_USER_HEADER=X-Forwarded-User

    Mode 3: LDAP 

    # .env
AUTH_MODE=ldap
LDAP_SERVER_URI=ldaps://ldap.example.com:636
LDAP_BASE_DN=dc=example,dc=com
LDAP_BIND_DN=cn=service-account,dc=example,dc=com
LDAP_BIND_PASSWORD=your-service-account-password
LDAP_USER_SEARCH_BASE=ou=users,dc=example,dc=com
LDAP_GROUP_SEARCH_BASE=ou=groups,dc=example,dc=com
    - Bind to the LDAP server with a service account, search for the user, then bind as the user to verify credentials - Map LDAP group membership to IPAM roles (Admin/User/ReadOnly) - Support both plain LDAP and LDAPS (TLS) - Implementation Structure: 
    # auth/models.py
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    password_hash = db.Column(db.String(255))  # Only for local auth
    role = db.Column(db.String(20), default='user')  # admin/user/readonly
    auth_type = db.Column(db.String(10), default='local')  # local/proxy
    is_active = db.Column(db.Boolean, default=True)

# auth/manager.py
class AuthManager:
    def authenticate_user(self, request):
        if app.config['AUTH_MODE'] == 'proxy':
            return self._authenticate_proxy(request)
        else:
            return self._authenticate_local(request)
    - Rationale: Maximum flexibility - simple setup for development/small deployments, enterprise-ready OIDC for larger organizations

🚫 Blocked/Deferred

Out of Scope

  • Multi-tenant Support: Not planned for current roadmap
  • Rationale: Single-tenant IPAM covers majority of use cases
  • Complexity: Would require significant architecture changes
  • Alternative: Deploy multiple IPAM instances for isolation

📈 Version History

v1.0.0 (Current)

  • ✅ Core IPAM functionality
  • ✅ Export/Import system with plugin architecture
  • ✅ Responsive web interface
  • ✅ Comprehensive test suite

v1.1.0 (Planned - Q4 2025)

  • 📅 Advanced export with filtering and templates
  • 📅 Network tools and calculator
  • 📅 Enhanced import formats (Excel, XML)
  • 📅 REST API expansion

v1.2.0 (Planned - Q1 2026)

  • 📅 Hybrid authentication system (local + OIDC)
  • 📅 User management interface
  • 📅 Role-based access control
  • 📅 IP lease history

v1.3.0 (Planned - Q2 2026)

  • 📅 IP conflict detection
  • 📅 Custom fields for hosts and networks

v2.0.0 (Planned - Q2 2026)

  • 📅 Network discovery tools
  • 📅 Advanced reporting and analytics
  • 📅 Performance optimizations for large datasets

📞 Need a new feature? Open a GitHub issue using the Feature Request template (.github/ISSUE_TEMPLATE/feature_request.yml).