IPAM & Network Discovery

Relevant source files

The following files were used as context for generating this wiki page:

• modules/ip_subnets/index.php
• modules/ip_addresses/index.php
• modules/ip_subnets/AGENT_NOTES.md
• modules/ip_addresses/AGENT_NOTES.md
• README.md
• scripts/api.php
• wiki/Modules.md

The IP Address Management (IPAM) and Network Discovery system provides a centralized framework for managing the lifecycle of network infrastructure within the IT Management System. It encompasses the definition of VLANs, the allocation of IP subnets (CIDR), and the tracking of individual IP addresses assigned to organizational assets.

The module facilitates both manual inventory management and automated network auditing through a built-in discovery tool that utilizes TCP connect probes to identify live hosts. This system is multi-tenant, ensuring that network configurations are strictly scoped to specific companies.

Sources: README.md:124-126, modules/ip_subnets/AGENT_NOTES.md:4-6, wiki/Modules.md:103-105

IP Subnet Management

The system manages IP subnets as CIDR blocks. Subnets are primary containers for IP addresses and are logically associated with VLANs and Companies.

Logical Structure and Rules

• Unique CIDR: Each CIDR block (e.g., 192.168.1.0/24) must be unique within a company context.
• VLAN Dependency: Subnets are linked to VLANs to maintain organizational hierarchy.
• Validation: The system enforces valid CIDR string formats and ensures that Gateway and DNS IP addresses defined for the subnet actually fall within the specified CIDR range.
• Usage Tracking: The system calculates usage statistics, such as Free vs. Used IPs, to assist administrators in capacity planning.

Sources: modules/ip_subnets/AGENT_NOTES.md:12-24, wiki/Modules.md:103-105

Data Model: Subnets

Field	Purpose
cidr	The network block in CIDR notation (e.g., /24).
company_id	Foreign key for multi-tenant isolation.
vlan_id	Association with a specific Virtual LAN.
gateway	Default gateway IP for the subnet.
dns_primary	Primary DNS server IP for the subnet.

Sources: modules/ip_subnets/AGENT_NOTES.md:8-10, modules/ip_subnets/index.php

IP Address Management

The IP Addresses module tracks the status and assignment of individual IPs within a defined subnet.

Functional Requirements

• Status Tracking: IPs are categorized into statuses such as free, used, reserved, or gateway.
• Equipment Integration: When an IP is assigned to a piece of equipment, the system links the equipment_id and can automatically update the associated hostname.
• Integrity: An IP must be unique within its parent subnet_id and the company context. It must also physically belong to the CIDR range of the selected subnet.

Sources: modules/ip_addresses/AGENT_NOTES.md:4-24, README.md:124-126

IPAM Relationship Diagram

The following diagram illustrates the relationship between network containers and physical assets.

Network Discovery & IP2WHOIS

Network Discovery is an active scanning feature located within the IP Subnets search interface. It allows administrators to identify active devices on the network without requiring external dependencies or shell execution.

Discovery Logic

The system performs an IPv4 range scan (supporting up to 255 addresses at once) using native PHP TCP connect probes. Unlike traditional scanners that might use exec or shell, this implementation is entirely internal to the application logic.

1. TCP Probing: The scanner attempts to connect to hosts in a specified range.
2. Subnet Matching: Responding hosts can be added to the IP Addresses inventory if they fall within a company-defined subnet.
3. Data Enrichment (IP2WHOIS): If an IP2WHOIS_API_KEY is configured in the environment or .env file, the system queries the IP2WHOIS Hosted Domains API to retrieve domain names associated with the live IP.
4. Inventory Creation: Upon clicking "Add to inventory," the retrieved domain name can be used as the default hostname for the IP record if the equipment does not already have one.

Sources: README.md:209-245, wiki/Modules.md:103-105

Discovery Flow

API Integration

The IPAM system exposes several AJAX endpoints for both interactive UI updates and bulk data processing.

Endpoint	Method	Purpose
modules/ip_subnets/index.php	POST	Handles AJAX actions for subnets and JSON imports via import_excel_rows.
modules/ip_addresses/index.php	POST	Handles IP status updates and JSON imports.

Sources: scripts/api.php:143-144, modules/ip_subnets/AGENT_NOTES.md:26-28

Code Pattern: Safe IP Selection

// Safe SELECT for IP Addresses within a specific company
$stmt = $conn->prepare("SELECT * FROM ip_addresses WHERE company_id = ? AND ip_text = ?");
$stmt->bind_param("is", $companyId, $ip);
$stmt->execute();

Sources: modules/ip_addresses/AGENT_NOTES.md:36-39

Conclusion

The IPAM & Network Discovery system ensures that the project's multi-tenant network data remains consistent and isolated. By combining CIDR validation, automated TCP discovery, and IP2WHOIS enrichment, the system provides a robust toolkit for managing complex network environments without external overhead.