netbox/THREAT_MODEL.md

NetBox Threat Model

Purpose & Scope

This document describes the security threat model for NetBox Community Edition, installed and operated according to the official documentation. Its purpose is to state explicitly who and what NetBox trusts, what a supported deployment looks like, and — most importantly — which classes of behavior are intended, privileged operations rather than security vulnerabilities.

NetBox is a feature-rich application that deliberately grants powerful capabilities (code execution, template rendering, outbound requests) to privileged users in order to support advanced network automation workflows. Many security reports we receive describe these intended capabilities as if they were defects. This document exists so that prospective reporters — and the maintainers who triage their reports — can quickly distinguish a genuine vulnerability from an authorized, privileged operation working as designed.

This document complements our Security Policy; it does not replace it. The policy governs how to report a suspected vulnerability and the conditions a report must meet. This document governs what constitutes a vulnerability in the first place.

This model anchors to OWASP's threat modeling guidance and uses a lightweight STRIDE breakdown (see below).

Supported Deployment Model

NetBox's threat model assumes a deployment consistent with the recommendations in our Security Policy and installation documentation:

• Not exposed to the public Internet. NetBox is intended to run on an internal or otherwise access-controlled network, behind a reverse proxy (e.g. nginx). It is not designed or hardened to serve as an anonymous, public-facing web application.
• Administered by trusted operators. The individuals who deploy, configure, and administer NetBox — including holders of the is_superuser flag and anyone with shell, filesystem, or database access to the host — are assumed to be trusted system administrators.
• The database is reachable only by the application. PostgreSQL and Redis are assumed to be accessible only to the NetBox application itself, not to arbitrary clients.
• An authenticated user base. NetBox is intended for use only by authenticated users. LOGIN_REQUIRED defaults to True, and support for unauthenticated access is being removed entirely in NetBox v5.0.
• The reverse proxy owns the network edge. TLS termination, HTTP request rate limiting, and authoritative determination of the client IP address are the responsibility of the deployment's reverse proxy and surrounding infrastructure — not the application. (See HTTP_CLIENT_IP_HEADERS; the headers NetBox trusts for client IP are only as trustworthy as the proxy that sets them.)

Reports that assume a deployment outside this model — for example, "an anonymous Internet user can reach the login page" or "an administrator can modify the database" — describe the intended operating environment, not a vulnerability.

Trusted vs. Untrusted Actors

The central question when evaluating any NetBox security report is: does the attack require a privilege that NetBox already designates as trusted?

Actor	Trust	Notes
The NetBox server / process	Trusted	Executes application code; holds secrets.
PostgreSQL database, Redis	Trusted	Assumed reachable only by the application.
Infrastructure operators	Trusted	Shell/filesystem/DB access implies total control by design.
Superusers (is_superuser)	Trusted	An active superuser bypasses all object-level permission checks. This is intentional.
Users permitted to author code-bearing objects	Trusted	Holders of permissions to create/modify custom scripts, export templates, config templates, custom links, or webhooks (see below).
Authenticated users without those permissions	Untrusted	Subject to full object-based permission enforcement.
Unauthenticated / network-adjacent parties	Untrusted	Outside the supported deployment model entirely.

The governing principle:

Granting a user permission to author a custom script, export or config template, custom link, or webhook is equivalent to granting that user a degree of code execution — by design. Abuse of such a feature by a user who holds the corresponding permission is not a vulnerability. The mitigation is administrative: grant these permissions only to trusted users, as instructed by the documentation for each feature.

Privileged-by-Design Features

The following features deliberately allow trusted users to supply code or logic that NetBox executes or renders. Each is gated by a specific permission and carries an explicit warning in its documentation. Using these features as designed — even in ways that read like "code execution" or "data access" to an outside observer — is not a vulnerability.

Custom Scripts

Custom scripts are Python modules with unrestricted access to the NetBox ORM, database, and Python runtime. They are gated by the extras.run_script permission (and authored by users who can add/modify script modules). The documentation states plainly that they are "inherently unsafe and should be installed and run only from trusted sources".

Export Templates, Config Templates, Custom Links & Webhooks (Jinja)

These features render user-authored Jinja templates with live application objects in scope. Templates are evaluated in a Jinja SandboxedEnvironment (netbox/utilities/Jinja.py), which restricts access to unsafe attributes and operations.

It is important to be precise about where the boundary lies:

• The sandbox is a boundary NetBox maintains. A genuine, reproducible escape from the sandbox — code or attribute access the sandbox is supposed to block — is a vulnerability we take seriously (see "In-Scope Vulnerabilities").
• Authoring these objects is nonetheless a privileged action. A template author legitimately has broad read access to NetBox objects and can produce arbitrary output within the sandbox's bounds. That a template can read data the author is otherwise permitted to see, or generate HTML/configuration, is intended behavior — not an injection vulnerability.

Each feature's documentation states that the relevant permission should be granted only to trusted users:

• Export templates
• Custom links
• Webhooks
• Configuration rendering

Webhooks & Event Rules (Outbound Requests)

Webhooks issue outbound HTTP requests to operator-defined URLs, with the URL, headers, and body all rendered from user-authored Jinja. A trusted webhook author can therefore direct requests to arbitrary endpoints. This server-side request capability is the entire purpose of the feature; it is available only to users permitted to create webhooks, and is not a server-side request forgery (SSRF) vulnerability when exercised by such a user.

Config Contexts & Custom Fields

Config contexts store arbitrary JSON applied to devices and virtual machines; custom fields add operator-defined attributes (with optional regex/JSON-schema validation). Neither executes code directly. Config context data may, however, be consumed by config templates during rendering, so it inherits the same "template author is trusted" posture described above.

Object-Based Permissions

NetBox enforces a robust object-based permission system layered on top of Django's model permissions. Permissions combine object types, users/groups, actions, and optional JSON constraints (including the special $user token). A failure of this system to enforce a permission or constraint that it advertises is a vulnerability (see below).

In-Scope Vulnerabilities

We take the following seriously. The common thread is a breach of a boundary NetBox claims to enforce, or harm to a user who never consented to the risk.

• Authorization bypass — reading or acting on objects a user has no permission to access.
• Privilege escalation — bypassing a permission or constraint to gain access beyond what was granted.
• Injection that crosses a data boundary — e.g. filter/ORM operator injection in the REST or GraphQL API exposing data a user shouldn't reach.
• Cross-site scripting (XSS) against a non-consenting victim — stored or DOM-based XSS that executes in another user's session.
• Jinja sandbox escapes — a reproducible escape from the template sandbox's intended restrictions.
• Authentication bypass and unauthenticated remote code execution or data access.
• Dependency vulnerabilities with a realistic exploit path through NetBox (not merely a flagged version).

Out-of-Scope / Non-Issues

The following are not treated as NetBox vulnerabilities. Most describe a privileged feature used by a user the documentation already designates as trusted, or a concern that belongs to the deployment/platform layer.

Scenario	Status	Reason
A permitted user runs code via a custom script, Jinja template, custom link, or webhook	Not a vulnerability	These features exist to execute user-authored logic; the required permission is trusted, operator-tier by design.
A superuser modifies the database, reads secrets, or creates another superuser	Not a vulnerability	Superusers and infrastructure operators are trusted by design.
A template author reads NetBox data they are otherwise permitted to view	Not a vulnerability	Template rendering with objects in scope is the purpose of the feature; the sandbox, not permission scoping, is the boundary.
Missing login/request rate limiting	Out of scope	A deployment-layer concern, handled by the reverse proxy rather than the application.
Client IP spoofing via X-Forwarded-For and similar headers	Out of scope	NetBox trusts the headers the reverse proxy sets; trustworthy client IP is a proxy responsibility (HTTP_CLIENT_IP_HEADERS).
Self-XSS (a user injecting script into their own session)	Not a vulnerability	The user is attacking only themselves; no privilege boundary is crossed.
CSRF on the login form	Not a vulnerability	Login CSRF is not a meaningful attack in NetBox's deployment model.
Automated-scanner reports that a file may be vulnerable	Rejected	Per our Security Policy, we do not accept reports from automated tooling that merely suggest potential vulnerability without a confirmed reproducible exploit.

Lightweight STRIDE View

Category	NetBox posture
Spoofing	Authentication via local accounts, LDAP, or SSO (python-social-auth); API tokens. Authoritative client-IP determination is delegated to the reverse proxy.
Tampering	All writes are gated by object-based permissions with optional constraints, validated within atomic transactions. Code-bearing objects are writable only by trusted users.
Repudiation	Changes are recorded via the changelog and journaling; event rules can emit notifications.
Information disclosure	Object-based view permissions filter every queryset. Cross-boundary disclosure (e.g. API/GraphQL filter injection) is in scope; data legitimately visible to a template author is not.
Denial of service	Request rate limiting and resource controls are a deployment/reverse-proxy responsibility, not the application's.
Elevation of privilege	The superuser flag is all-or-nothing and trusted. Any unintended escalation across the permission system (constraint bypass, action bypass) is in scope.

Triage & Severity

When triaging a report we assess the CVSS environmental score, not solely the base score. A finding with a high CVSS base score may be downgraded substantially once NetBox's deployment assumptions and trust boundaries are applied — for example, a "remote code execution" that in fact requires a permission we already designate as trusted (script or template authoring) is mitigated by design rather than by a code change.

We use CVSS v3.1/v4.0 for scoring and the STRIDE categories above to reason about boundaries. If you believe you have a fix that closes an in-scope issue without degrading the affected feature, you are welcome to propose it alongside your report.

Reporting

Before reporting, please confirm that the behavior you've observed is an in-scope vulnerability under this document and not an intended, privileged operation, and that it is reproducible in the current stable release of NetBox.

To report a suspected vulnerability, follow the process in our Security Policy. In summary, a report must:

• Affect the most recent stable release of NetBox, or a current beta release;
• Affect a NetBox instance installed and configured per the official documentation; and
• Be reproducible following a prescribed set of instructions.

Confidential reports may be sent to security@netboxlabs.com.