Asset management is not the fun part of security. It means collecting serial numbers, fixing inconsistent hostnames, matching IP addresses to interfaces, identifying system owners, and asking whether a server that appears in DNS still exists.
It is also work that has to happen.
In Cybersecurity Asset Inventory, I discussed why asset management comes before appropriate security controls. You cannot decide what to protect, how strongly to protect it, or what to recover first if you do not know what exists.
Criticality is tied to business function. A server is not critical simply because it is expensive or technically complicated. It is critical because payroll depends on it, customers authenticate through it, employees cannot work without it, or its compromise would expose sensitive information. The better you understand what an asset does for the business, the better you can judge its security requirements.
The NIST Cybersecurity Framework 2.0 reflects that relationship. Its Asset Management category calls for inventories of hardware, software, systems, services, and facilities, then calls for prioritizing those assets by classification, criticality, resources, and operational impact.[3]
A spreadsheet can handle the first few assets. It becomes harder to maintain once the environment includes racks, switches, hypervisors, virtual machines, VLANs, prefixes, interfaces, cloud systems, and services that depend on one another. That is where NetBox becomes useful.
What NetBox does
NetBox is an open-source application for modeling infrastructure and network state. Its data model covers physical devices, racks, sites, interfaces, cabling, virtualization, IP addressing, VLANs, circuits, and related infrastructure objects.[1]
The important word is modeling. NetBox is a source of truth, not a passive discovery appliance. It does not watch network traffic and automatically build a perfect inventory. An operator, script, integration, or reconciliation process still has to supply and verify the data.
That distinction keeps the tool useful:
- NetBox records the infrastructure state you intend and have verified.
- Hypervisors, switches, DNS, DHCP, Kubernetes, and cloud APIs report live state.
- Reconciliation compares the two and exposes drift.
NetBox is also not a replacement for every asset-related system. It is particularly good at infrastructure and network relationships. It is not a place to track software licenses, purchase orders, depreciation, or employee equipment assignments. Those records belong in tools built for those jobs.
Where it helps with security and compliance
An accurate infrastructure inventory gives security work a foundation. It helps answer practical questions:
- Which systems are exposed to the internet?
- Which devices belong to the management VLAN?
- Where does a critical service run?
- Which virtual machine depends on which hypervisor?
- Which IP address is assigned to a specific interface?
- Which assets should be restored first after an outage?
NetBox can also support documentation and evidence needs that appear in security frameworks, assessments, contracts, and compliance programs. It can show that an organization maintains infrastructure records, associates addresses with systems, documents network segmentation, and reviews changes over time.
NetBox maintains an object-level change log when records are created, updated, or deleted. Those records include the changed object, the user and request involved, and snapshots of the data before and after the change.[6]
It does not make an organization compliant on its own. A technically accurate device record may still be missing the business owner, data classification, recovery priority, or review history required by the organization’s obligations. NetBox supplies useful technical evidence, but the surrounding asset-management process still needs ownership and business context.
This is especially useful for small and medium-sized businesses. Many do not need, or want to pay for, a large commercial configuration-management platform. NetBox provides a capable open-source option without a large software-license bill. The tradeoff is operational responsibility: somebody still has to host it, patch it, back it up, control access, and keep its records current.
Building the first site in the GUI
The easiest way to understand NetBox is to create a small set of related objects through the web interface. For a fictional office, I would build the inventory in this order.
1. Create the site and location
Under Organization > Sites, create a site named Main Office.
Then create a location named Server Room beneath that site. Locations let you describe where equipment sits without creating a separate site for every room or floor.
2. Add a rack
Under DCIM > Racks, create the server-room rack and enter its height. Even when the rack is not full, recording device positions makes maintenance easier later. It also exposes impossible documentation, such as two devices assigned to the same rack unit.
3. Define the device metadata
Before adding equipment, create the supporting records NetBox expects:
- Manufacturer
- Device type
- Device role
- Platform
For example, a switch might use the role Network Switch and the platform Cisco IOS XE. A virtualization host might use Hypervisor and Proxmox VE.
4. Add the device and its interfaces
Create the switch or server, assign it to the site and location, and place it in the rack if appropriate. Then add its actual interface names.
Preserve the names used by the device. If the switch calls an interface GigabitEthernet1/0/24, record that instead of shortening it to something more convenient. Accurate names make later API reconciliation much easier.
5. Add VLAN and IP address information
Create a VLAN group scoped to the site, then add the VLANs used there. Add the relevant prefixes and assign IP addresses to device interfaces.
Once the interface and address exist, set the appropriate address as the device’s primary IP. NetBox can now show the relationship among the device, interface, address, VLAN, prefix, location, and rack instead of storing each fact in an unrelated spreadsheet column.
6. Add virtualization
For a virtualization platform, create a cluster, associate its physical hosts, and add the stable virtual machines running on it. This is where NetBox becomes more than a rack diagram. It can represent that a service runs on a VM, the VM belongs to a cluster, and the cluster depends on specific physical hosts.
Using the REST API
NetBox exposes a REST API to create, read, update, and delete objects. Its documentation also provides an interactive API interface, and authenticated requests use tokens issued through NetBox.[2]
For a simple shell workflow, store the URL and token in environment variables or, better, a secrets manager such as Vault.
export NETBOX_URL='https://netbox.example.com/api'
export NETBOX_TOKEN='replace-with-your-token'Do not type a real long-lived token directly into a command that will be retained in shell history. An expanded authorization header can also be visible in process arguments while curl is running. For repeated automation, retrieve the credential through Vault and let the automation supply it at runtime.
NetBox supports more than one token format. Depending on the token type and NetBox version, the authorization scheme may be Bearer or Token; use the format shown by the token page and documentation for your installation.[2]
Create a site
Before creating an object, query a unique field such as the slug. This prevents duplicates each time the script runs.
curl --fail-with-body \
-H "Authorization: Bearer $NETBOX_TOKEN" \
-H 'Accept: application/json' \
"$NETBOX_URL/dcim/sites/?slug=main-office"If the response contains no matching site, create it:
curl --fail-with-body \
-X POST "$NETBOX_URL/dcim/sites/" \
-H "Authorization: Bearer $NETBOX_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data '{
"name": "Main Office",
"slug": "main-office",
"status": "active"
}'Create a VLAN in an existing group
Do not hardcode an object ID from a test system. Look up the VLAN group by its slug and use the ID returned by NetBox:
GROUP_ID=$(curl --fail-with-body \
-H "Authorization: Bearer $NETBOX_TOKEN" \
-H 'Accept: application/json' \
"$NETBOX_URL/ipam/vlan-groups/?slug=main-office-vlans" \
| jq -r '.results[0].id')
if [ -z "$GROUP_ID" ] || [ "$GROUP_ID" = "null" ]; then
echo "VLAN group main-office-vlans was not found" >&2
exit 1
fiThen create the VLAN:
curl --fail-with-body \
-X POST "$NETBOX_URL/ipam/vlans/" \
-H "Authorization: Bearer $NETBOX_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data "{
\"vid\": 20,
\"name\": \"Management\",
\"status\": \"active\",
\"group\": $GROUP_ID
}"A production automation workflow should go further:
- Query before writing.
- Create an absent object with
POST. - Update an existing object by ID with
PATCH. - Read the exact object back after the write.
- Stop and show the response body when NetBox rejects the data.
HTTP success only proves that the server accepted a request. Reading the object back proves that the intended record now exists with the expected values.
Let Hermes handle the repetitive work
The GUI and API examples show how NetBox works. They do not mean every asset has to be entered through a browser or copied into curl commands by hand.
I used the same credential pattern described in Replacing Hermes Agent .env Files with HashiCorp Vault. Vault stores the NetBox URL and API token with the credentials for the Hermes profile responsible for infrastructure work. When the profile starts, Hermes retrieves the values through its command secret source instead of keeping the NetBox token in the task, script, or article.[4]
Before allowing writes, I would start with a preview-only pass and require approval for the proposed changes. Whatever the NetBox token can do, Hermes can do, so that access should be chosen deliberately. Writes should still use lookup-before-create behavior and read-back verification.
With access to NetBox and approved infrastructure sources, I can give Hermes a task such as:
Compare the current NetBox inventory with the virtualization hosts, network configuration, DNS, and Kubernetes infrastructure. Create missing records, update verified changes, stop on conflicts, and read each object back after writing it.
Hermes can then handle the repetitive sequence:
- Retrieve the NetBox credentials from Vault.
- Query NetBox to see which objects already exist.
- Collect current information from the approved source systems.
- Normalize names and map the data to NetBox’s object relationships.
- Create missing records or update verified changes in dependency order.
- Read the records back and report conflicts or failed validation.
Dependency order matters in NetBox. A site and location need to exist before a rack or device can reference them. A device needs an interface before you can assign an IP address to it. A virtualization cluster needs its hosts before virtual machines can be associated with the right infrastructure. Hermes can keep track of that sequence across a much larger inventory than I would want to enter manually.
The automation should stop when its sources disagree rather than guessing. One sanitized result from this inventory work looked like this:
REVIEW REQUIRED
Evidence: DNS and HAProxy still reference an application endpoint.
Live verification: No deployed application was found.
NetBox action: Excluded from inventory after operator confirmation.This still requires human judgment. Hermes can determine whether a virtual machine exists, where it runs, and which address it has. It cannot determine on its own whether that system supports payroll, customer authentication, or another critical business function. The people who understand the business still have to assign ownership and criticality.
Record the change as it happens
NetBox’s change log records what happened to individual NetBox objects. A separate change-management record can capture why the work happened, who requested it, which external systems were queried, and which conflicts required review.
Hermes supports lifecycle hooks that can run before a model request, after a tool call, and at the end of a session. Those hooks can log activity, send notifications, or post information to another system.[5] A NetBox workflow could use them to create or update a record in Multica or another change-management database.
For example, the change record could contain:
- Who requested the inventory update
- Which source systems were queried
- Which NetBox objects were created or changed
- Which writes were read back successfully
- Which conflicts were left for human review
- When the work started and completed
The hook should record the action and result, not secrets or complete API responses. The NetBox token remains in Vault, while the change system receives a useful audit trail of what Hermes attempted and what NetBox accepted.
For a small or medium-sized business, this turns asset management from a large manual data-entry project into a reviewed workflow. Hermes handles the repetitive collection and API work, while the operator verifies the results and supplies the business context that determines criticality and security priority.
Sources
[1] https://netboxlabs.com/docs/netbox [2] https://netboxlabs.com/docs/netbox/v4.5/integrations/rest-api [3] https://tsapps.nist.gov/publication/get_pdf.cfm?pub_id=957258 [4] https://hermes-agent.nousresearch.com/docs/user-guide/secrets/command [5] https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks [6] https://netboxlabs.com/docs/netbox/models/core/objectchange/