{"id":35145234,"url":"https://github.com/tuxpeople/python-ipam","last_synced_at":"2026-01-12T08:31:15.306Z","repository":{"id":317827513,"uuid":"1068994006","full_name":"tuxpeople/python-ipam","owner":"tuxpeople","description":"Modern IP Address Management (IPAM) system with Flask REST API, Bootstrap UI, and enterprise-grade security. Built on Chainguard distroless containers with 0 vulnerabilities.","archived":false,"fork":false,"pushed_at":"2025-12-28T22:02:28.000Z","size":215,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-30T22:22:17.773Z","etag":null,"topics":["bootstrap","chainguard","distroless","docker","flask","ip-address-management","ipam","network-management","python","rest-api","security","sqlalchemy"],"latest_commit_sha":null,"homepage":"https://tuxpeople.github.io/python-ipam/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuxpeople.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-03T08:31:06.000Z","updated_at":"2025-12-28T22:02:31.000Z","dependencies_parsed_at":"2025-10-06T09:01:40.289Z","dependency_job_id":null,"html_url":"https://github.com/tuxpeople/python-ipam","commit_stats":null,"previous_names":["tuxpeople/python-ipam"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/tuxpeople/python-ipam","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxpeople%2Fpython-ipam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxpeople%2Fpython-ipam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxpeople%2Fpython-ipam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxpeople%2Fpython-ipam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuxpeople","download_url":"https://codeload.github.com/tuxpeople/python-ipam/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxpeople%2Fpython-ipam/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrap","chainguard","distroless","docker","flask","ip-address-management","ipam","network-management","python","rest-api","security","sqlalchemy"],"created_at":"2025-12-28T13:41:08.450Z","updated_at":"2026-01-12T08:31:15.300Z","avatar_url":"https://github.com/tuxpeople.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python IPAM - IP Address Management System\n\nA modern, web-based IP Address Management (IPAM) system built with Flask, SQLite, Bootstrap, and DataTables.\n\n## Features\n\n- 🌐 **Network Management**: Manage IP networks with CIDR notation\n- 🖥️ **Host Management**: Track IP addresses, hostnames, and MAC addresses\n- 🔌 **REST API**: Complete RESTful API with Swagger UI documentation\n- 📊 **Dashboard**: Clear overview of network utilization\n- 🔍 **Advanced Search**: DataTables integration for efficient data filtering\n- 📱 **Responsive Design**: Bootstrap 5 for modern, mobile-friendly UI\n- 🐳 **Container-ready**: Docker support for easy deployment\n- ✅ **Fully Tested**: Comprehensive unit tests with pytest\n\n## Local Development with pyenv\n\n### Prerequisites\n\n1. **Install pyenv** (if not already installed):\n\n   **macOS with Homebrew:**\n   ```bash\n   brew install pyenv\n   ```\n\n   **Linux/macOS with curl:**\n   ```bash\n   curl https://pyenv.run | bash\n   ```\n\n2. **Shell Configuration** (for bash/zsh):\n   ```bash\n   echo 'export PATH=\"$HOME/.pyenv/bin:$PATH\"' \u003e\u003e ~/.bashrc\n   echo 'eval \"$(pyenv init -)\"' \u003e\u003e ~/.bashrc\n   echo 'eval \"$(pyenv virtualenv-init -)\"' \u003e\u003e ~/.bashrc\n   source ~/.bashrc\n   ```\n\n### Setup\n\n1. **Clone repository:**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd ipam\n   ```\n\n2. **Install and activate Python version:**\n   ```bash\n   pyenv install 3.13\n   pyenv local 3.13\n   ```\n\n3. **Create virtual environment:**\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # Linux/macOS\n   # or\n   venv\\\\Scripts\\\\activate  # Windows\n   ```\n\n4. **Install dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n5. **Configure environment variables:**\n   ```bash\n   cp .env.example .env\n   # Edit .env as needed\n   ```\n   Optional host assignment behavior:\n   - `HOST_ASSIGN_ON_CREATE=true` marks new hosts as assigned by default.\n   API authentication and rate limiting:\n   - `API_TOKENS=token1,token2` enables token auth for `/api/v1` (empty disables).\n   - `API_RATE_LIMIT=200 per minute` sets the global API limit.\n   - `RATELIMIT_ENABLED=true` toggles rate limiting.\n   - `RATELIMIT_STORAGE_URI=memory://` sets the Flask-Limiter backend.\n\n6. **Initialize database (migrations):**\n   ```bash\n   export FLASK_APP=app.py\n   flask db upgrade\n   ```\n   For new schema changes, create a migration first:\n   ```bash\n   flask db migrate -m \"describe change\"\n   flask db upgrade\n   ```\n\n7. **Start application:**\n   ```bash\n   python app.py\n   ```\n\n   The application will be available at:\n   - **Web Interface**: http://localhost:5000\n   - **REST API**: http://localhost:5000/api/v1\n   - **API Documentation (Swagger UI)**: http://localhost:5000/api/v1/docs\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Tests with coverage report\npytest --cov=app --cov-report=html\n\n# Run specific tests\npytest tests/test_models.py\n\n# Tests in watch mode (with pytest-watch)\npip install pytest-watch\nptw\n```\n\n## Docker Deployment\n\n### Production Container (Chainguard Distroless)\n\nThe production Docker image is built on **Chainguard distroless Python images** for maximum security:\n\n**Security Features:**\n- ✅ **0 CRITICAL/HIGH vulnerabilities** (Trivy scanned)\n- ✅ Multi-stage build with minimal attack surface\n- ✅ Distroless runtime (no shell, package manager)\n- ✅ Runs as nonroot user (UID 65532)\n- ✅ Includes SBOM (Software Bill of Materials)\n- ✅ Python 3.13\n\n**Image Details:**\n- **Size**: ~50-100MB (vs 200-300MB for standard Python images)\n- **Base**: cgr.dev/chainguard/python:latest (distroless)\n- **Registry**: ghcr.io/tuxpeople/python-ipam\n\n```bash\n# Pull and run production image\ndocker pull ghcr.io/tuxpeople/python-ipam:latest\ndocker run -d -p 5000:5000 \\\n  -v $(pwd)/ipam.db:/app/ipam.db \\\n  ghcr.io/tuxpeople/python-ipam:latest\n\n# The container runs migrations automatically on startup.\n# Set IPAM_RUN_MIGRATIONS=false to disable.\n\n# Or use Docker Compose\ndocker-compose up -d\n\n# With custom .env file\ncp .env.example .env\n# Edit .env for production settings\ndocker-compose up -d\n```\n\n### Development\n\n```bash\n# Development environment with hot-reload\ndocker-compose --profile dev up\n\n# Or build locally\ndocker build -t python-ipam:dev .\ndocker run -p 5000:5000 python-ipam:dev\n```\n\n## REST API\n\nThe complete REST API is available at `/api/v1`. Interactive API documentation (Swagger UI) can be found at http://localhost:5000/api/v1/docs\nAPI endpoints require a token when `API_TOKENS` is configured. Use\n`Authorization: Bearer \u003ctoken\u003e` or `X-API-Key: \u003ctoken\u003e`. Rate limiting\ncan be enabled with `RATELIMIT_ENABLED=true` and configured via\n`API_RATE_LIMIT` and `RATELIMIT_STORAGE_URI`.\n\n### Main Endpoints:\n\n**Networks:**\n- `GET /api/v1/networks` - List all networks with filtering and pagination\n- `GET /api/v1/networks/{id}` - Get specific network\n- `POST /api/v1/networks` - Create new network\n- `PUT /api/v1/networks/{id}` - Update network\n- `DELETE /api/v1/networks/{id}` - Delete network\n\n**Hosts:**\n- `GET /api/v1/hosts` - List all hosts with filtering and pagination\n- `GET /api/v1/hosts/{id}` - Get specific host\n- `POST /api/v1/hosts` - Create new host\n- `PUT /api/v1/hosts/{id}` - Update host\n- `DELETE /api/v1/hosts/{id}` - Delete host\n\n**IP Management:**\n- `GET /api/v1/ip/networks/{id}/next-ip` - Get next available IP\n- `GET /api/v1/ip/networks/{id}/available-ips` - List all available IPs\n- `GET /api/v1/ip/{ip_address}` - Query IP address status\n\nSee [API.md](API.md) for complete documentation\n\n## Project Structure\n\n```\nipam/\n├── app.py                 # Flask application entry point\n├── requirements.txt       # Python dependencies\n├── pytest.ini            # Pytest configuration\n├── Dockerfile            # Docker container definition\n├── docker-compose.yml    # Docker Compose configuration\n├── .env.example          # Example environment variables\n├── ipam/                 # Main application package\n│   ├── __init__.py       # Application Factory\n│   ├── extensions.py     # Flask extensions (SQLAlchemy)\n│   ├── models.py         # Database models\n│   ├── forms.py          # WTForms\n│   ├── config.py         # Configuration\n│   ├── api/              # REST API Blueprint\n│   │   ├── __init__.py   # API Blueprint and Swagger\n│   │   ├── models.py     # API serialization models\n│   │   ├── networks.py   # Network endpoints\n│   │   ├── hosts.py      # Host endpoints\n│   │   └── ip_management.py  # IP management endpoints\n│   └── web/              # Web Interface Blueprint\n│       ├── __init__.py   # Web Blueprint\n│       └── routes.py     # Web routes\n├── templates/            # HTML Templates (Jinja2)\n│   ├── base.html         # Base template\n│   ├── index.html        # Dashboard\n│   ├── networks.html     # Network overview\n│   ├── hosts.html        # Host overview\n│   ├── add_network.html  # Add network\n│   ├── add_host.html     # Add host\n│   ├── edit_network.html # Edit network\n│   └── edit_host.html    # Edit host\n├── exporters/            # Export plugins\n│   ├── base_exporter.py  # Base exporter class\n│   ├── csv_exporter.py   # CSV export\n│   ├── json_exporter.py  # JSON export\n│   └── dnsmasq_exporter.py  # DNSmasq config export\n├── importers/            # Import plugins\n│   ├── base_importer.py  # Base importer class\n│   ├── csv_importer.py   # CSV import\n│   └── json_importer.py  # JSON import\n└── tests/                # Test suite\n    ├── conftest.py       # Pytest fixtures\n    ├── test_models.py    # Model tests\n    ├── test_routes.py    # Route tests\n    ├── test_forms.py     # Form tests\n    ├── test_database.py  # Database tests\n    ├── test_export_import.py  # Export/Import tests\n    └── test_crud_operations.py  # CRUD tests\n```\n\n## Database Schema\n\n### Networks Table\n- `id` - Primary Key\n- `network` - Network address (e.g., \"192.168.1.0\")\n- `cidr` - CIDR suffix (e.g., 24)\n- `broadcast_address` - Broadcast address\n- `name` - Network name (optional)\n- `domain` - DNS domain (optional)\n- `vlan_id` - VLAN ID (optional)\n- `description` - Description (optional)\n- `location` - Location (optional)\n\n### Hosts Table\n- `id` - Primary Key\n- `ip_address` - IP address (unique)\n- `hostname` - Hostname (optional)\n- `cname` - DNS alias/CNAME (optional)\n- `mac_address` - MAC address (optional)\n- `description` - Description (optional)\n- `status` - Status (active/inactive/reserved)\n- `is_assigned` - Whether the host is officially assigned\n- `last_seen` - Last observed timestamp (ISO 8601)\n- `discovery_source` - Discovery source identifier\n- `network_id` - Foreign Key to Networks\n\nNote: After upgrading, run `flask db upgrade` to apply schema changes. If\nyour database predates Alembic migrations, run\n`flask db stamp 7b4a1d0f9b2a` before `flask db upgrade`.\n\n### DHCP Ranges Table\n- `id` - Primary Key\n- `network_id` - Foreign Key to Networks\n- `start_ip` - Range start IP address\n- `end_ip` - Range end IP address\n- `description` - Description (optional)\n- `is_active` - Whether the range is active\n\n## Backups \u0026 Restore\n\nBackups are stored in `BACKUP_DIR` (default: `./backups`).\n\n**CLI commands**:\n```bash\nexport FLASK_APP=app.py\nflask backup create\nflask backup list\nflask backup verify ipam-backup-YYYYmmdd-HHMMSSZ.db\nflask backup restore ipam-backup-YYYYmmdd-HHMMSSZ.db\n```\n\n**Scheduled backups** (cron example):\n```bash\n0 3 * * * cd /path/to/python-ipam \u0026\u0026 FLASK_APP=app.py flask backup create\n```\n\n## Development Guidelines\n\n1. **Code Style**: Follow PEP 8\n2. **Tests**: Write tests for new features\n3. **Commits**: Use meaningful commit messages\n4. **Branches**: Use feature branches for new development\n\n## Technology Stack\n\n- **Backend**: Flask 3.1, SQLAlchemy 2.0, Flask-RESTX\n- **Frontend**: Bootstrap 5, jQuery, DataTables\n- **Database**: SQLite (production-ready for small to medium deployments)\n- **Testing**: pytest, pytest-flask (96 tests)\n- **Containerization**: Docker (Chainguard distroless), Docker Compose\n- **Security**: Trivy scanning, SBOM generation, multi-stage builds\n- **CI/CD**: GitHub Actions (tests, security scans, docs deployment)\n\n## License\n\n[Specify license here]\n\n## Contributing\n\nContributions are welcome! Please create issues for bug reports or feature requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuxpeople%2Fpython-ipam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuxpeople%2Fpython-ipam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuxpeople%2Fpython-ipam/lists"}