# Netbox Review Integration

> >

- **Type:** Skill
- **Install:** `agentstack add skill-netboxlabs-skills-netbox-review-integration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [netboxlabs](https://agentstack.voostack.com/s/netboxlabs)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [netboxlabs](https://github.com/netboxlabs)
- **Source:** https://github.com/netboxlabs/skills/tree/main/skills/netbox-review-integration

## Install

```sh
agentstack add skill-netboxlabs-skills-netbox-review-integration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# NetBox Integration Code Review

> **Your knowledge of NetBox APIs may be outdated.** Verify specific API behaviors, limits, and patterns against current documentation before flagging issues.

## Retrieval Sources

| Source | URL / Method | Use for |
|--------|-------------|---------|
| NetBox REST API docs | `https://netboxlabs.com/docs/netbox/integrations/rest-api/` | Current endpoint behavior |
| pynetbox repo | `https://github.com/netbox-community/pynetbox` | SDK method signatures |
| Diode Python SDK | `https://github.com/netboxlabs/diode-sdk-python` | Ingestion API patterns |
| NetBox MCP server | If configured — verify object schemas and filter availability | Field validation |

## Review Workflow

Follow this checklist when reviewing NetBox integration code:

1. **Verify retrieval** — Check current API docs for any endpoints/patterns you're unsure about
2. **Read the full file** — understand the integration's intent before flagging issues
3. **Check authentication** — token format, header usage, credential storage
4. **Check pagination** — all list endpoints must handle pagination
5. **Check performance** — config_context exclusion, brief mode, filter specificity
6. **Check error handling** — HTTP errors, rate limits, timeouts, partial failures
7. **Check data integrity** — correct use of PATCH vs PUT, bulk operation atomicity
8. **Provide evidence** — reference specific line numbers and explain why something is wrong

## Critical Rules

### Authentication (AUTH)

| ID | Rule | Severity |
|----|------|----------|
| AUTH-1 | Use `nbt_`-prefixed v2 tokens on NetBox 4.5+ | High |
| AUTH-2 | Never hardcode tokens in source — use env vars or secrets manager | Critical |
| AUTH-3 | Use `Bearer` prefix in Authorization header (not `Token` on 4.5+) | High |
| AUTH-4 | Verify token has required permissions for all accessed endpoints | Medium |
| AUTH-5 | Flag reliance on v1 (`Token `) tokens — deprecated in 4.6, **removed in v5.0**; migrate to v2. On 4.6.1+ the v2 plaintext is shown once at creation, so capture it then | High |

### Pagination (PAG)

| ID | Rule | Severity |
|----|------|----------|
| PAG-1 | All list endpoint calls MUST handle pagination (follow `next` links) | Critical |
| PAG-2 | Never assume all results fit in one response — even small collections grow | High |
| PAG-3 | Set explicit `limit` parameter — don't rely on server default (50) | Medium |
| PAG-4 | GraphQL queries MUST include `pagination: {limit: N}` at every list level | Critical |
| PAG-5 | Nested GraphQL lists need their own pagination parameters | High |
| PAG-6 | Prefer cursor pagination over deep offsets for large reads — REST `?start=` (4.6+), GraphQL `pagination: {start: N, limit: M}` (4.5.2+); flag deep `?offset=` scans | Medium |

### Performance (PERF)

| ID | Rule | Severity |
|----|------|----------|
| PERF-1 | Exclude `config_context` from device/VM list queries (`?exclude=config_context`) | Critical |
| PERF-2 | Use `?brief=True` for reference lookups and dropdowns | High |
| PERF-3 | Use specific filters (`name__ic=`, `site_id=`) instead of `?q=` at scale | High |
| PERF-4 | Use `?fields=` to select only needed fields | Medium |
| PERF-5 | Parallelize independent API calls — don't serialize unrelated requests | Medium |
| PERF-6 | Use bulk endpoints (POST/PATCH/DELETE arrays) instead of per-object calls | High |
| PERF-7 | GraphQL depth must stay ≤ 3, never exceed 5 | High |

### Error Handling (ERR)

| ID | Rule | Severity |
|----|------|----------|
| ERR-1 | Handle HTTP 4xx/5xx responses — don't assume success | Critical |
| ERR-2 | Implement retry with backoff for 429 (rate limit) and 5xx errors | High |
| ERR-3 | Handle partial success in bulk operations (all-or-nothing semantics) | Medium |
| ERR-4 | Check `response.errors` on Diode ingestion responses | High |
| ERR-5 | Handle branch async job failures (poll until terminal status) | High |

### Data Integrity (DATA)

| ID | Rule | Severity |
|----|------|----------|
| DATA-1 | Use PATCH for updates — PUT replaces entire objects, clearing omitted fields | Critical |
| DATA-2 | Include `id` in each object for bulk PATCH/DELETE operations | High |
| DATA-3 | Use natural keys (slug/name) for readability but be aware of uniqueness constraints | Medium |
| DATA-4 | Validate dependency order for REST creates (parent before child) | High |
| DATA-5 | IPAddress values MUST include CIDR prefix length (`/24`, not bare IP) | High |
| DATA-6 | For tag edits, prefer write-only `add_tags`/`remove_tags` (4.6+) over read-modify-write of the full `tags` list — the latter clobbers concurrent writers' tags | Medium |
| DATA-7 | For read-modify-write on a single object under concurrency, use ETag + `If-Match` (4.6+); a 412 response means the object changed — re-fetch and retry rather than blind overwrite | Medium |

## Anti-Patterns to Flag

| Anti-Pattern | Why It Matters | Fix |
|-------------|---------------|-----|
| No pagination loop | Silently drops data beyond first page | Follow `next` links until null |
| `?q=` for bulk filtering | Full-text search is slow at scale | Use specific filter expressions |
| PUT for partial updates | Clears fields you didn't intend to change | Use PATCH |
| Hardcoded token in source | Security vulnerability | Use environment variable |
| Sequential single-object creates | 100x slower than bulk | Use array POST to list endpoint |
| Ignoring `config_context` in list queries | 10-100x slower responses | Add `?exclude=config_context` |
| Catching bare `Exception` on API calls | Hides real errors | Catch `requests.HTTPError` specifically |
| No timeout on HTTP requests | Hangs indefinitely on network issues | Set `timeout=30` |
| GraphQL without pagination params | Omitting `pagination` returns **all** rows; `pagination` without `limit` returns Strawberry's default **100** (not the REST default of 50) — both silently differ from expectations | Always pass `pagination: {limit: N}` explicitly |
| Polling branch jobs without backoff | Wastes API calls, may trigger rate limits | Exponential backoff (1s → 30s) |

## Scope

This skill covers **code that calls NetBox APIs**. It does NOT cover:
- NetBox plugin internals → use [netbox-plugin-development](../netbox-plugin-development/SKILL.md)
- Data model design quality → use [netbox-review-datamodel](../netbox-review-datamodel/SKILL.md)
- NetBox server administration → use [netbox-administration](../netbox-administration/SKILL.md)

## Principles

- **Be certain.** Retrieve current API docs before flagging version-specific issues.
- **Provide evidence.** Reference line numbers and explain the actual failure mode.
- **Focus on correctness.** A working integration that's slightly verbose is better than a broken clever one.
- **Severity matters.** Critical issues break functionality. High issues degrade performance or reliability. Medium issues affect maintainability.
- **Don't over-flag.** If code works correctly for its specific use case (e.g., small dataset that fits in one page), note the limitation but don't mark it critical.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [netboxlabs](https://github.com/netboxlabs)
- **Source:** [netboxlabs/skills](https://github.com/netboxlabs/skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-netboxlabs-skills-netbox-review-integration
- Seller: https://agentstack.voostack.com/s/netboxlabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.