PowerNetbox

The comprehensive PowerShell module for the Netbox REST API with 100% coverage — 520+ cmdlets across DCIM, IPAM, Virtualization, Circuits, Tenancy, VPN, Wireless, and the netbox-branching plugin.
Cross-platform (PowerShell 5.1 / 7+), fully compatible with Netbox 4.7.0 (supports 4.3+).

📖 Full documentation: docs.powernetbox.dev

This project is a fork of the original NetboxPS created by Ben Claussen.

We extend our sincere thanks to Ben and all original contributors for building the foundation of this module. Their work made PowerNetbox possible.

# Install
Install-Module -Name PowerNetbox -Scope CurrentUser

# Connect (paste your NetBox API token when prompted)
$cred = Get-Credential -UserName 'api'
Connect-NBAPI -Hostname 'netbox.example.com' -Credential $cred

# Query
Get-NBDCIMDevice -Brief

Full install options (PS 5.1 vs 7+, platform-specific, manual build), connection and authentication details, and worked examples are in the documentation:

The NetBox API, by default, treats all query parameter values as case-sensitive. As PowerShell is as case-insensitive as possible, the module offers an option to use case-insensitive query values.

Set-NBQueryOption -IgnoreCase:$true or Connect-NBAPI -IgnoreCase.

By default, the module uses filter queries, that ask for an exact match.
You can influence this behaviour by choosing between three modes: Exact, Wildcard, Regex. Every API string parameter, which supports regex/iregex operators, is enabled

1. Exact: The search string is sent 1:1 through the API
2. Wildcard: Wildcard characters in the search string, are taken into account for filtering query results.
3. Regex: Search strings accept Regex tokens for filtering result sets. Please keep in mind, that regex is matching parts of a string!

Set-NBQueryOption -MatchMode Wildcard|Regex or Connect-NBAPI -Matchmode.

Every Get-NB* cmdlet for a taggable model has -Tag <slug[]> and -Tag_Id <id[]>. Multiple values are combined with AND by NetBox (the object must carry all of them). Set-NBQueryOption -TagMatch Any switches to NetBox 4.6.6+ tag__any / tag_id__any (object carries at least one). Below 4.6.6 the option is ignored on purpose, because an unknown lookup would silently return every object.

Set-NBQueryOption -TagMatch Any
Get-NBDCIMDevice -Tag 'edge', 'core'          # edge OR core
Get-NBDCIMDevice -Name 'core-01' | Set-NBObjectTag -Add 'maintenance' -Remove 'staging'   # partial tag update (4.6+)

-Tags on New-*/Set-* accepts tag names or IDs (names are sent as { "name": ... }, which is what the API requires).

Set-NBQueryOption -Pagination Cursor makes -All walk large tables with NetBox's ?start=<pk> cursor instead of limit/offset, which stays fast on very large result sets. Results come back ordered by primary key. Older servers fall back to offset paging automatically; an explicit -Offset always wins.

Set-NBQueryOption -OptimisticConcurrency remembers the ETag of every object you read and sends it as If-Match on the next Set-*/Remove-* of that object. If someone changed the object in between, NetBox answers 412 Precondition Failed and the error tells you to re-read and retry, instead of silently overwriting their change.

The bulk-capable New-*/Set-*/Remove-* cmdlets (see the bulk operations guide) take -Background: each batch is queued as a NetBox background job (?background=true, HTTP 202) and the job objects are returned, so very large batches no longer hit proxy timeouts. Inspect the outcome with Get-NBJob. Needs an RQ worker on the server.

Depending on the version of the NetBox API used, the API supports these options for a specific set of parameters and endpoints. Due to this current limitation, the module can only support case insensitivity and wildcard searches for the same set of cases.

• Minimum version of Netbox API is 4.4+.
• A list of parameters offered by each API version can be found in the repository. See _IgnoreCaseParameters.ps1. Each parameter is paired with an exception list of endpoints. This means it is supported on all endpoints which are not part of the list.

PowerShell 5.1 (Windows Desktop) or 7.0+ (Windows / macOS / Linux), and NetBox 4.3+ (tested against 4.3.7, 4.4.10, 4.5.10, 4.6.10, 4.7.0). Version-specific behaviour and the support matrix are documented in the Compatibility guide.

Contributions are welcome. Fork the repo, branch from dev, follow the PowerShell Practice and Style Guidelines, and open a pull request against dev. See CONTRIBUTING.md for the full workflow.

• Vulnerability reporting: see SECURITY.md. Use GitHub Security Advisories for private disclosure.
• Privacy: see PRIVACY.md. PowerNetbox sends requests only to the NetBox host you configure — no telemetry, no analytics.
• Recent security reviews: docs/superpowers/reviews/.

PowerNetbox is distributed unsigned on PSGallery. Authenticity is anchored in GitHub's Sigstore-backed build-provenance attestations, produced automatically for every release by actions/attest-build-provenance.

Verify a downloaded module:

$module = Get-Module -ListAvailable PowerNetbox |
    Sort-Object Version -Descending |
    Select-Object -First 1

gh attestation verify $module.Path `
    --repo ctrl-alt-automate/PowerNetbox

Additional trust anchors: PSGallery publisher identity (ctrl-alt-automate), signed git release tags, and the public MIT-licensed source at each tag.

Note on Authenticode: PowerNetbox has no Authenticode signature, so Get-AuthenticodeSignature will report NotSigned — this is expected. An OSS code-signing certificate may be revisited if the project grows enough to qualify for a Foundation-backed program.

This project is licensed under the MIT License — see the LICENSE file for details.

Original copyright (c) 2018 Ben Claussen. Fork maintained by ctrl-alt-automate.