n8n-nodes-netbox-connector 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -28
- package/dist/package.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,25 +1,61 @@
|
|
|
1
1
|
# n8n-nodes-netbox-connector
|
|
2
2
|
|
|
3
|
+
<img src="https://raw.githubusercontent.com/eduardez/n8n-nodes-netbox-connector/main/nodes/NetBoxConnector/netbox-logo.svg" alt="NetBox network symbol" width="80">
|
|
4
|
+
|
|
3
5
|
Repository: [n8n-nodes-netbox-connector](https://github.com/eduardez/n8n-nodes-netbox-connector) · Homepage: [README](https://github.com/eduardez/n8n-nodes-netbox-connector#readme) · npm package: [n8n-nodes-netbox-connector](https://www.npmjs.com/package/n8n-nodes-netbox-connector) · Issues: [GitHub Issues](https://github.com/eduardez/n8n-nodes-netbox-connector/issues)
|
|
4
6
|
|
|
7
|
+
n8n action node for NetBox infrastructure automation, combining a schema-generated REST catalog, Custom REST, read-only GraphQL, and IP address/prefix provisioning helpers.
|
|
8
|
+
|
|
5
9
|
Contributions are welcome—feel free to contribute!
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
NetBox is a registered trademark of NetBox Labs. The network-symbol artwork is derived from the official NetBox logo at <https://github.com/netbox-community/netbox/blob/v4.7.3/netbox/project-static/img/logo_netbox_bright_teal.svg> and is used here as the symbol portion only. The full source logo is copyrighted by its respective owner. This project is not affiliated with or endorsed by NetBox Labs.
|
|
12
|
+
|
|
13
|
+
## Contents
|
|
14
|
+
|
|
15
|
+
- [Installation](#installation)
|
|
16
|
+
- [Credentials](#credentials)
|
|
17
|
+
- [Quick start](#quick-start)
|
|
18
|
+
- [Resources](#resources)
|
|
19
|
+
- [Errors, output, and security](#errors-output-and-security)
|
|
20
|
+
- [Development](#development)
|
|
21
|
+
- [CI/CD and integration tests](#cicd-and-integration-tests)
|
|
22
|
+
- [Changelog](#changelog)
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
8
25
|
|
|
9
|
-
|
|
26
|
+
On self-hosted n8n, an Owner/Admin can install `n8n-nodes-netbox-connector` from **Settings → Community Nodes → Install**. See the [n8n GUI installation guide](https://docs.n8n.io/integrations/community-nodes/installation-and-management/gui-installation). Restart n8n if prompted. The package requires Node.js `>=20.15`; no minimum installed n8n version is specified here.
|
|
10
27
|
|
|
11
|
-
|
|
28
|
+
### Manual install (custom nodes folder)
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
mkdir -p ~/.n8n/custom
|
|
32
|
+
cd ~/.n8n/custom
|
|
33
|
+
npm init -y
|
|
34
|
+
npm install n8n-nodes-netbox-connector
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Set `N8N_CUSTOM_EXTENSIONS=~/.n8n/custom` (or use the default custom-node lookup) and restart n8n.
|
|
12
38
|
|
|
13
39
|
## Credentials
|
|
14
40
|
|
|
15
41
|
Create **NetBox API** credentials:
|
|
16
42
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
|
|
43
|
+
| Field | Meaning | Example |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
| Base URL | Deployment root, optionally with reverse-proxy subpath; do not append `/api` or `/graphql` | `https://netbox.example.com/netbox` |
|
|
46
|
+
| Token Type | Version 2 (Bearer) or Version 1 (Token) | `Version 2 (Bearer)` |
|
|
47
|
+
| API Token | Full v2 token in `nbt_<key>.<token>` form, or plaintext v1 token | *(enter in n8n)* |
|
|
48
|
+
| Allow Unauthorized Certificates | Skips TLS certificate validation; keep disabled | `false` |
|
|
49
|
+
|
|
50
|
+
Version 1 tokens are deprecated in NetBox 4.6 and later. Credential testing first calls `/api/authentication-check/`. If that endpoint is absent (HTTP 404), it probes the protected, read-only `/api/users/users/?limit=1`; an explicit permission-denied response is accepted only when it confirms the token authenticated but lacks user-list permission. It never falls back to unauthenticated `/api/status/`. Requests use the configured origin and deployment subpath; caller-supplied `Authorization`, `Host`, and `Cookie` headers cannot override transport security.
|
|
21
51
|
|
|
22
|
-
|
|
52
|
+
## Quick start
|
|
53
|
+
|
|
54
|
+
1. Add a **Manual Trigger**.
|
|
55
|
+
2. Add **NetBox Connector**, select the saved **NetBox API** credential, then choose **GraphQL → Query**.
|
|
56
|
+
3. Set **Query** to `query { __typename }` and execute.
|
|
57
|
+
|
|
58
|
+
The output preserves GraphQL `data` and `errors`. This read-only query includes no token, credential ID, or write operation.
|
|
23
59
|
|
|
24
60
|
## Resources
|
|
25
61
|
|
|
@@ -55,38 +91,41 @@ GET and HEAD requests do not accept a body. For multipart or binary requests, ma
|
|
|
55
91
|
|
|
56
92
|
Array responses produce one n8n item per element. Helpers and all resources use the same credentials, timeout validation, error handling, and redaction.
|
|
57
93
|
|
|
58
|
-
## Errors and
|
|
94
|
+
## Errors, output, and security
|
|
59
95
|
|
|
60
96
|
HTTP failures include the status and redacted NetBox response details. With **Continue On Fail**, the node emits an error item for the failing input item and continues; successful outputs retain input-item pairing. A 204 or HEAD response produces an empty JSON object unless response metadata is enabled.
|
|
61
97
|
|
|
98
|
+
Use HTTPS, keep certificate validation enabled, grant least privilege, and store credentials in n8n's credential store. Disabling certificate validation permits interception; trusting a self-signed server does not make that bypass safe. Never place secrets in workflow JSON or screenshots. GraphQL is read-only, but REST operations and IPAM helpers include writes; selectors do not make the entire connector read-only.
|
|
99
|
+
|
|
100
|
+
Base URLs configured with HTTP send the API token without TLS protection. Catalog generation also accepts a remote schema URL and can attach `NETBOX_TOKEN`; use HTTPS for authenticated schema inputs and never send that token to an HTTP URL. Catalog generation is optional and does not run during installation or routine tests.
|
|
101
|
+
|
|
62
102
|
## Development
|
|
63
103
|
|
|
104
|
+
Routine offline checks:
|
|
105
|
+
|
|
64
106
|
```sh
|
|
65
|
-
npm
|
|
66
|
-
npm run generate
|
|
67
|
-
npm run check:coverage
|
|
107
|
+
npm ci --ignore-scripts
|
|
68
108
|
npm test
|
|
69
109
|
npm run lint
|
|
110
|
+
npm run check:coverage
|
|
70
111
|
npm pack --dry-run
|
|
71
112
|
```
|
|
72
113
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
## CI/CD
|
|
76
|
-
|
|
77
|
-
Pull requests, pushes to `main` or `develop`, and manual dispatch run **CI** on Node.js 20 and 22. It installs locked dependencies, builds, checks generated-operation coverage, runs lint and tests, and verifies `npm pack --dry-run`.
|
|
114
|
+
### Optional catalog maintenance
|
|
78
115
|
|
|
79
|
-
|
|
116
|
+
Catalog regeneration is optional; it is not required to install, build, or test the checked-in catalog:
|
|
80
117
|
|
|
81
|
-
|
|
118
|
+
```sh
|
|
119
|
+
npm run generate -- --input <path-or-url>
|
|
120
|
+
```
|
|
82
121
|
|
|
83
|
-
The
|
|
122
|
+
The generator uses `scripts/schema/netbox-4.7.3.openapi.json` by default. For remote authenticated inputs, `NETBOX_TOKEN` and optional `NETBOX_TOKEN_TYPE` are used; only use trusted HTTPS URLs for authenticated schema fetches.
|
|
84
123
|
|
|
85
|
-
|
|
124
|
+
## CI/CD and integration tests
|
|
86
125
|
|
|
87
|
-
|
|
126
|
+
Pull requests, pushes to `main` or `develop`, and manual dispatch run **CI** on Node.js 20 and 22. It installs locked dependencies, builds, checks generated-operation coverage, runs lint and tests, and verifies `npm pack --dry-run`.
|
|
88
127
|
|
|
89
|
-
|
|
128
|
+
CI dispatch also accepts `run_integration` (default false). Set it to true to run `npm run test:integration` against a disposable NetBox instance; configure `NETBOX_BASE_URL`, `NETBOX_API_TOKEN`, and `NETBOX_TEST_PREFIX_ID`. Confirm the target is disposable before dispatch. The create/delete tag scenario remains disabled unless **Allow writes** is selected; choose token type `v1` or `v2`.
|
|
90
129
|
|
|
91
130
|
`npm run test:integration` runs the compiled node against a disposable NetBox instance. Set `NETBOX_INTEGRATION_DISPOSABLE=1`, `NETBOX_BASE_URL`, `NETBOX_API_TOKEN`, and `NETBOX_TEST_PREFIX_ID`; `NETBOX_TOKEN_TYPE` defaults to `v2`. The suite covers native paginated REST, Custom REST metadata, a read-only GraphQL query, and IPAM read helpers.
|
|
92
131
|
|
|
@@ -94,7 +133,7 @@ The create/delete tag scenario is skipped unless `NETBOX_INTEGRATION_ALLOW_WRITE
|
|
|
94
133
|
|
|
95
134
|
```sh
|
|
96
135
|
NETBOX_INTEGRATION_DISPOSABLE=1 \
|
|
97
|
-
NETBOX_BASE_URL='https://<disposable-netbox>' \
|
|
136
|
+
NETBOX_BASE_URL='https://<disposable-netbox.example.com>' \
|
|
98
137
|
NETBOX_API_TOKEN='<token>' \
|
|
99
138
|
NETBOX_TEST_PREFIX_ID='<prefix-id>' \
|
|
100
139
|
npm run test:integration
|
|
@@ -102,11 +141,15 @@ npm run test:integration
|
|
|
102
141
|
|
|
103
142
|
The integration harness executes the compiled node with an HTTP adapter; it does not launch an n8n server or verify the browser UI.
|
|
104
143
|
|
|
105
|
-
|
|
144
|
+
Every change merged to `main` triggers `publish.yml`. Conventional Commits select the version: `fix:` is patch, `feat:` is minor, and `feat!:` or `BREAKING CHANGE:` is major. Other commit types, including `docs` and `chore`, produce a patch release.
|
|
106
145
|
|
|
107
|
-
|
|
108
|
-
- **0.1.0** — Initial NetBox 4.7.3 catalog, authenticated transport, Custom REST, read-only GraphQL, and IPAM provisioning helpers
|
|
146
|
+
The source `package.json` may retain its development version. The release runner sets the calculated version only in the npm artifact; its `vX.Y.Z` tag and GitHub release refer to the same source commit and version.
|
|
109
147
|
|
|
110
|
-
|
|
148
|
+
For recovery after a failed automatic publish, dispatch **Actions → Publish → Run workflow** from `main` with the exact version of the existing `vX.Y.Z` tag. The workflow builds that tag's commit, requires it to be an ancestor of `main`, and skips an existing npm version only when its registry `gitHead` matches. With no existing tag, a manual version must exceed both the highest stable git tag and npm `latest`. The workflow never commits or pushes a version change to `main`.
|
|
111
149
|
|
|
150
|
+
Configure the npm **Trusted Publisher** for owner `eduardez`, repository `n8n-nodes-netbox-connector`, and workflow filename `publish.yml` only. Leave the environment blank and allow direct `npm publish`; the workflow uses Node 22 and npm 11.19.0 with OIDC, not an npm token.
|
|
151
|
+
|
|
152
|
+
## Changelog
|
|
112
153
|
|
|
154
|
+
- **0.1.1** — Add a protected credential-test fallback for NetBox releases without `/api/authentication-check/`.
|
|
155
|
+
- **0.1.0** — Initial NetBox 4.7.3 catalog, authenticated transport, Custom REST, read-only GraphQL, and IPAM provisioning helpers.
|
package/dist/package.json
CHANGED