@knowttl/artium-axi 0.0.23 → 0.0.25
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 +119 -281
- package/bin/artium-axi.mjs +2142 -263
- package/package.json +1 -1
- package/skill/artium-axi/SKILL.md +93 -3
package/README.md
CHANGED
|
@@ -1,331 +1,169 @@
|
|
|
1
1
|
# artium-axi
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[](LICENSE)
|
|
6
|
-
[](https://www.npmjs.com/package/@knowttl/artium-axi)
|
|
7
|
-
[](package.json)
|
|
8
|
-
[](https://github.com/knowttl/artium-axi/attestations)
|
|
9
|
-
|
|
10
|
-
[Quickstart](#quickstart) • [Use with your agent](#use-with-your-agent) • [Features](#features) • [Safety](#safety) • [Configuration](#configuration) • [Commands](#commands)
|
|
11
|
-
|
|
12
|
-
```mermaid
|
|
13
|
-
flowchart LR
|
|
14
|
-
Agent[Agent or human] --> CLI[Artium CLI]
|
|
15
|
-
CLI -->|HTTPS and Artium identity| Server[Artium server]
|
|
16
|
-
Admin[Administrator] -->|Browser administration| Server
|
|
17
|
-
Server --> Store[Encrypted credentials and audit]
|
|
18
|
-
Server --> Runner[Bounded tool runner]
|
|
19
|
-
Runner --> APIs[Vendor APIs]
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
## Why this exists
|
|
3
|
+
Client CLI and embedded skill for the Artium managed tools server.
|
|
23
4
|
|
|
24
|
-
|
|
25
|
-
Artium runs pinned tools on a shared server, checks each user's roles and supplies the service credential after audited admission.
|
|
26
|
-
Agents keep a command-line interface with TOON discovery rather than implementing each vendor's REST authentication or an MCP integration.
|
|
5
|
+
[](https://www.npmjs.com/package/@knowttl/artium-axi) [](LICENSE) [](package.json) [](https://github.com/knowttl/artium-axi/attestations) [](https://github.com/knowttl/axi)
|
|
27
6
|
|
|
28
|
-
|
|
7
|
+
[Why this exists](#why-this-exists) · [Quickstart](#quickstart) · [Use with your agent](#use-with-your-agent) · [What it covers](#what-it-covers) · [Safety](#safety) · [Configuration](#configuration) · [Output and exit codes](#output-and-exit-codes) · [Troubleshooting](#troubleshooting) · [Contributing](#contributing) · [Security](#security) · [License](#license)
|
|
29
8
|
|
|
30
|
-
|
|
31
|
-
- **Credentials:** encrypted shared service identities, private per-call profiles and credential tests.
|
|
32
|
-
- **Discovery:** available tools, cached health, pinned versions and contextual first-call suggestions.
|
|
33
|
-
- **Agent setup:** managed skills for Claude Code, Codex, OpenCode and Pi; optional Claude Code session hook.
|
|
34
|
-
- **Audit:** authentication, administration and tool-call records with filtered CSV/JSON-lines export.
|
|
35
|
-
- **Limits:** reviewed command inventories, write switches, bounded runtime, output and concurrency.
|
|
9
|
+
## Why this exists
|
|
36
10
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
| Vectra | Token or OAuth; optional allow-listed writes |
|
|
42
|
-
| Azure | Application identity and resource-token broker |
|
|
43
|
-
| Microsoft Graph | Application identity; optional allow-listed writes |
|
|
44
|
-
| LDAP | Verified TLS simple bind; read-only |
|
|
45
|
-
| Azure DevOps | PAT or application identity |
|
|
46
|
-
| GitHub | Shared identity; see [supported authentication and capabilities](#safety) |
|
|
47
|
-
| AWX | Pasted token or one-time password sign-in; optional operational writes |
|
|
48
|
-
| Tenable One | Access and secret API keys; optional allow-listed business writes and export jobs |
|
|
49
|
-
| Hybrid Analysis | Managed API key; investigation reads and optional allow-listed submissions, YARA mutations and consuming matches |
|
|
50
|
-
| Check Point Email Security | Regional client credentials; email, event, task and exception reads, guarded writes and authenticated email/attachment saving |
|
|
51
|
-
|
|
52
|
-
[Package pins](tools/package.json), the [GitHub CLI release pin](tools/gh-source.json) and the [Falcon source pin](tools/falcon-source.json) own bundled versions; [reviewed inventories](tools/inventories) define the supported command boundary.
|
|
11
|
+
Separate vendor CLIs put credentials, access controls and API guesswork on every agent host.
|
|
12
|
+
Artium runs pinned tools on a shared server for agents and the humans running them, checking roles and supplying server-held credentials after audited admission.
|
|
13
|
+
Bounded execution, TOON discovery and contextual next steps help agents find a permitted read before attempting a gated write.
|
|
14
|
+
Administrators deploy and configure the server; client users sign in and discover their granted tools.
|
|
53
15
|
|
|
54
16
|
## Quickstart
|
|
55
17
|
|
|
56
|
-
|
|
57
|
-
Give this prompt to the agent helping you administer the server:
|
|
58
|
-
|
|
59
|
-
> Deploy artium-axi on my Linux host.
|
|
60
|
-
> Check Docker/Compose, host capacity, ports, DNS and the HTTPS/TLS plan first.
|
|
61
|
-
> Use the repository's Compose file to build the server, or a published image only after verifying its release digest and provenance as described in the runbook.
|
|
62
|
-
> Generate an exactly 32-byte random master key into a protected file, make it readable by container UID 10001, and keep an offline escrow copy separate from database backups.
|
|
63
|
-
> Create the first administrator through the documented first-start password-file bootstrap, change its temporary password and remove bootstrap inputs.
|
|
64
|
-
> Configure tool credentials through the administrator UI, test each credential, enable the intended tools and grant roles.
|
|
65
|
-
> Run liveness, readiness and a permitted read for each enabled tool; report results and remaining limits without secrets.
|
|
66
|
-
> Never ask me to paste passwords, tokens or keys into chat or command arguments.
|
|
67
|
-
> Use hidden prompts, protected stdin or files with safe permissions for secrets.
|
|
68
|
-
> Follow docs/admin-guide.md, docs/tool-credentials.md and docs/runbook.md for the exact steps.
|
|
69
|
-
|
|
70
|
-
For manual deployment, follow the [administrator guide](docs/admin-guide.md#set-up-a-host).
|
|
71
|
-
|
|
72
|
-
### Verified client
|
|
73
|
-
Use Linux with Node **24.11.0+**, curl and sha256sum, and obtain the trusted HTTPS URL and account from your administrator.
|
|
74
|
-
For a private CA, set `ARTIUM_AXI_CA_FILE` to a readable PEM file and add `--cacert "$ARTIUM_AXI_CA_FILE"` to both curl commands.
|
|
18
|
+
Use Linux with Node **24.11.0+** and a trusted HTTPS server URL and account from your administrator.
|
|
75
19
|
|
|
76
20
|
```sh
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
curl --fail --output artium-axi.mjs "$ARTIUM_AXI_URL/cli/artium-axi.mjs" &&
|
|
81
|
-
curl --fail --output artium-axi.mjs.sha256 "$ARTIUM_AXI_URL/cli/artium-axi.mjs.sha256" &&
|
|
82
|
-
sha256sum --check artium-axi.mjs.sha256 &&
|
|
83
|
-
mv artium-axi.mjs artium-axi &&
|
|
84
|
-
chmod 755 artium-axi &&
|
|
85
|
-
rm artium-axi.mjs.sha256
|
|
86
|
-
export PATH="$HOME/.local/bin:$PATH"
|
|
21
|
+
npm install --global @knowttl/artium-axi
|
|
22
|
+
artium-axi doctor
|
|
23
|
+
# Without a global install: npx -y @knowttl/artium-axi doctor
|
|
87
24
|
```
|
|
88
25
|
|
|
89
|
-
|
|
90
|
-
|
|
26
|
+
Before configuration, doctor reports failures such as `fail: server address (CLIENT_CONFIG_INVALID)`.
|
|
27
|
+
Configure and sign in, then discover a first read:
|
|
91
28
|
|
|
92
29
|
```sh
|
|
30
|
+
export ARTIUM_AXI_URL='https://artium.example.test'
|
|
93
31
|
artium-axi login --username synthetic-user
|
|
94
|
-
artium-axi
|
|
32
|
+
artium-axi
|
|
95
33
|
artium-axi tools show falcon-axi
|
|
96
34
|
artium-axi falcon-axi detection list
|
|
97
35
|
```
|
|
98
36
|
|
|
99
|
-
|
|
100
|
-
For
|
|
101
|
-
For
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
For clients without `update`, repeat the verified download and checksum check above to install the server's current client.
|
|
105
|
-
For `CLI_OUTDATED`, the server uses the client version header to select the update hint or safe download guidance; the capability boundary is defined by `firstVersionWithUpdate` in [the version contract](src/shared/version.ts).
|
|
106
|
-
The updater uses those connection settings, verifies the server download’s SHA-256, replaces the running client file and keeps the previous client beside it as `<client-file>.bak`.
|
|
107
|
-
The client file and its directory must be writable.
|
|
108
|
-
The Falcon read requires an enabled tool, a role grant and API permissions; choose the example from an available tool's detail view.
|
|
109
|
-
|
|
110
|
-
With no enabled tools granted, `artium-axi tools` succeeds with:
|
|
111
|
-
|
|
112
|
-
```text
|
|
113
|
-
tools: 0 available
|
|
114
|
-
reason: No enabled runtime tool is available through your assigned roles.
|
|
115
|
-
contact: Ask an administrator to check your role assignments and enabled tools.
|
|
116
|
-
next[1]:
|
|
117
|
-
- artium-axi whoami
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
### npm client alternative
|
|
121
|
-
The server download supplies its matching client; npm is an alternative client-only distribution.
|
|
122
|
-
|
|
123
|
-
```sh
|
|
124
|
-
npm install -g @knowttl/artium-axi
|
|
125
|
-
export ARTIUM_AXI_URL='https://artium.example.test'
|
|
126
|
-
artium-axi login --username synthetic-user
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
Login warns about version differences; minimum server API requirements still apply.
|
|
130
|
-
`artium-axi update` refuses npm installations; update them with `npm install -g @knowttl/artium-axi@latest`.
|
|
131
|
-
Install `@knowttl/artium-axi@<server-version>` or download from the server to match it.
|
|
132
|
-
|
|
133
|
-
### Build from source
|
|
134
|
-
Use Node 24.11.0+, pnpm 10.22.0, OpenSSL, Python 3, curl and sha256sum on Linux.
|
|
135
|
-
|
|
136
|
-
```sh
|
|
137
|
-
git clone https://github.com/knowttl/artium-axi.git
|
|
138
|
-
cd artium-axi
|
|
139
|
-
pnpm install --frozen-lockfile
|
|
140
|
-
pnpm build
|
|
141
|
-
node dist/cli/artium-axi.mjs --help
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
Use `node dist/cli/artium-axi.mjs` in place of `artium-axi` for the same login and discovery steps.
|
|
145
|
-
The root install also installs frozen upstream dependencies; native build approval is limited to argon2, better-sqlite3 and esbuild.
|
|
146
|
-
`pnpm build:npm` stages the public client in `dist/npm`; `npm pack --dry-run ./dist/npm` inspects its contents.
|
|
37
|
+
Login prompts privately for a password; replace the synthetic account and choose a tool granted to you.
|
|
38
|
+
For SSO, use `artium-axi login --sso` and approve only your terminal's browser code.
|
|
39
|
+
For a private CA, set `ARTIUM_AXI_CA_FILE` to a readable PEM file before login.
|
|
40
|
+
Login saves connection settings; shared service credentials and tool profiles are configured by administrators.
|
|
41
|
+
See [verified server downloads and updates](docs/client-reference.md#verified-client) or [server deployment](docs/admin-guide.md#set-up-a-host).
|
|
147
42
|
|
|
148
43
|
## Use with your agent
|
|
149
44
|
|
|
150
|
-
After
|
|
45
|
+
After sign-in, install managed skills and the optional Claude Code discovery hook:
|
|
151
46
|
|
|
152
47
|
```sh
|
|
153
48
|
artium-axi setup --host claude --hook
|
|
154
49
|
```
|
|
155
50
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
51
|
+
For Codex, OpenCode or Pi, use `--host codex`, `--host opencode` or `--host pi` without `--hook`.
|
|
52
|
+
The Claude `SessionStart` hook injects `tools` output; skills teach managed command discovery and grant no permissions.
|
|
53
|
+
Artium's authenticated setup fetches granted tools' adapted skills; a standalone skill installer does not configure this server account.
|
|
54
|
+
Start with the [compact investigation guide](skill/artium-axi/SKILL.md#investigation-quick-guide) in the base skill.
|
|
55
|
+
See the [command reference](docs/commands.md) and authenticated `artium-axi tools show <tool>` for commands.
|
|
56
|
+
Re-run setup after moving the executable or changing grants.
|
|
57
|
+
To remove the hook, delete only objects labelled `statusMessage: "artium-axi managed tools"` from `hooks.SessionStart` in the Claude host's `settings.json`.
|
|
58
|
+
See [installation paths and manual skill removal](docs/client-reference.md#agent-installation).
|
|
59
|
+
|
|
60
|
+
<a id="features"></a>
|
|
61
|
+
<a id="commands"></a>
|
|
62
|
+
|
|
63
|
+
## What it covers
|
|
64
|
+
|
|
65
|
+
All twelve managed tools start disabled; role grants, enabled tools and upstream permissions determine access.
|
|
66
|
+
Write capabilities below require administrator opt-in.
|
|
67
|
+
|
|
68
|
+
| Group | Purpose | Access | Reference |
|
|
69
|
+
| --- | --- | --- | --- |
|
|
70
|
+
| BeyondTrust PM Cloud | Endpoint Privilege Management reads, selected writes, deletes and four downloads | Managed credentials; exact operation grants; separate delete toggle | [Credentials](docs/tool-credentials.md#beyondtrust-pm-cloud) |
|
|
71
|
+
| Discovery and sessions | Identity, login, tools, doctor, update and setup | Client/session operations | [Commands](docs/commands.md) |
|
|
72
|
+
| Falcon | Endpoint investigations, guarded RTR and MalQuery | Reads; selected execution/search | [Capabilities](docs/safety.md#write-gates-by-tool) |
|
|
73
|
+
| Vectra | Hosts, detections and response workflows | Reads; selected writes | [Credentials](docs/tool-credentials.md#vectra) |
|
|
74
|
+
| Azure | Subscriptions, resources and queries | Reads; reviewed writes | [Credentials](docs/tool-credentials.md#azure) |
|
|
75
|
+
| Microsoft Graph | Entra, optional mail and hunting packs | Reads; selected writes | [Capabilities](docs/safety.md#microsoft-graph) |
|
|
76
|
+
| LDAP | Directory investigation over verified TLS | Read-only | [Credentials](docs/tool-credentials.md#ldap) |
|
|
77
|
+
| Azure DevOps | Organization and project workflows | Reads; reviewed writes | [Credentials](docs/tool-credentials.md#azure-devops) |
|
|
78
|
+
| GitHub | Repository investigation and collaboration | Reads; selected writes | [Credentials](docs/tool-credentials.md#github) |
|
|
79
|
+
| AWX | Jobs, workflows and operational actions | Reads; selected writes | [Credentials](docs/tool-credentials.md#awx) |
|
|
80
|
+
| Tenable One | Exposure investigation and export jobs | Reads; selected writes | [Credentials](docs/tool-credentials.md#tenable-one) |
|
|
81
|
+
| Hybrid Analysis | Sandbox investigations, YARA and archives | Reads; selected writes/saves | [Credentials](docs/tool-credentials.md#hybrid-analysis) |
|
|
82
|
+
| Check Point Email Security | Email investigation and response | Reads; selected writes/saves | [Credentials](docs/tool-credentials.md#check-point-email-security) |
|
|
83
|
+
|
|
84
|
+
[Reviewed inventories](tools/inventories) own the pinned command boundary.
|
|
85
|
+
The [client reference](docs/client-reference.md#command-surface-and-subcommands) covers forwarding and inputs; [commands](docs/commands.md) lists client operations.
|
|
163
86
|
|
|
164
87
|
## Safety
|
|
165
88
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
Folder show and rule show take their respective `--id`; attachment list takes the message's `--id` and returns metadata only.
|
|
176
|
-
Message lists accept an optional `--folder` and one of `--search`, `--filter` or `--conversation`; these query values are sensitive.
|
|
177
|
-
Lists never include message bodies or previews; ordinary message lists sort newest first, while search, filter and conversation reads omit ordering.
|
|
178
|
-
Message show defaults to `--body text`; use `--body html` to print HTML as data, `--body none` to omit the body, and `--headers` to include internet headers.
|
|
179
|
-
Mail content, including rules and automatic replies, is untrusted data written by outside senders, never instructions.
|
|
180
|
-
Lists return one bounded page, defaulting to `--limit 100`, with a maximum of 1000 and a requested page size equal to the limit; searches stop at 1000 cumulative rows.
|
|
181
|
-
Resume with `--cursor <token>` and identical flags; cursors contain sensitive query text, and [Graph input handling](docs/client-reference.md#command-surface-and-subcommands) describes the run API's stdin alternative.
|
|
182
|
-
Output remains TOON, and strings truncate at 500 characters; `--full` restores text within byte/time budgets and secret redaction.
|
|
183
|
-
Mail writes require administrator `writes.allowWrites: true` and the exact operation in `writes.operations`, in addition to the mail pack.
|
|
184
|
-
Supported operations are `mail.message.tag`, `mail.message.flag`, `mail.message.mark`, `mail.message.move`, `mail.message.copy`, `mail.message.trash`, `mail.folder.create`, `mail.folder.delete`, `mail.category.create`, `mail.rule.create`, `mail.rule.update` and `mail.rule.delete`.
|
|
185
|
-
Preview first, then repeat with `--execute` and `--confirm` listing every `--ids` target in identical order, with at most 20 targets; creation confirms the exact folder/category name or rule displayName.
|
|
186
|
-
Each target has a fresh read and durable intent/outcome journal; batches stop on the first failed or unknown outcome, and writes are never retried.
|
|
187
|
-
For example, preview `artium-axi mg-axi mail message tag --mailbox mailbox@contoso.example --ids <id1>,<id2> --add Reviewed` before confirming with `--execute --confirm <id1>,<id2>`.
|
|
188
|
-
Tagging preserves other categories and unchanged values are no-ops; move/copy/trash return the old and new IDs, and trash moves to Deleted Items.
|
|
189
|
-
Folder deletion requires empty custom folders without child folders and readable well-known folder IDs; a fresh check cannot prevent concurrent mailbox changes.
|
|
190
|
-
Rule create/update accepts exactly one UTF-8 JSON upload through `--file rule.json`, at most 64 KiB; the CLI uploads local content, never a server path or stdin.
|
|
191
|
-
Rule files are schema-checked and reject forwarding, redirect and permanent-delete actions.
|
|
192
|
-
Use `artium-axi download` for separately selected `mail.attachment.save` and `mail.message.export` operations, with scoped Application Mail.Read, the mail pack and write opt-in.
|
|
193
|
-
See the [hosted saving path](docs/client-reference.md#microsoft-graph-mail-saving) for selectors, confirmation, limits and safe handling of untrusted mail content.
|
|
194
|
-
Ordinary tool-run downloads, sending, reply, forward and permanent deletion remain unavailable.
|
|
195
|
-
Raw `api get` mail routes and `--expand` remain refused; Graph mail error bodies are suppressed.
|
|
196
|
-
See [Graph credential setup](docs/tool-credentials.md#microsoft-graph) for scoped mailbox authorization and credential-test limitations.
|
|
197
|
-
Administrators can opt in to the single read-only `security hunting query` command for Defender XDR advanced hunting with `enabledPacks: ["entra", "security"]` in the managed tool settings.
|
|
198
|
-
Hunting accepts exactly one UTF-8 plain-text upload named `query.kql`, at most 64 KiB, through `artium-axi mg-axi security hunting query --file query.kql`.
|
|
199
|
-
See [client input handling](docs/client-reference.md#command-surface-and-subcommands) for local file paths and upload restrictions.
|
|
200
|
-
Queries must use the upstream restricted read-only KQL subset.
|
|
201
|
-
Hunting parses KQL before the read-only allowlist and upstream authentication; syntax errors return positioned diagnostics without query excerpts or quoted literals.
|
|
202
|
-
Parsing does not check tables, columns, types or permissions; recognized Graph 400 errors expose only the error class and line/column, while unknown error shapes remain opaque.
|
|
203
|
-
The existing mg-axi role grant is required; other security commands remain unavailable.
|
|
204
|
-
See [Graph credential setup](docs/tool-credentials.md#microsoft-graph) for hunting permissions and consent; tenant acceptance remains unverified.
|
|
205
|
-
|
|
206
|
-
Azure Resource Graph and Log Analytics queries parse KQL before upstream authentication or requests, returning positioned syntax diagnostics and query excerpts on failure.
|
|
207
|
-
Successful parsing does not validate tables, columns, functions, permissions or service-specific restrictions.
|
|
208
|
-
|
|
209
|
-
Falcon investigation reads include detection lineage, process details and trees, existing sandbox reports, FileVantage changes and device-control policy details.
|
|
210
|
-
NG-SIEM `search start` checks CQL structure before upstream authentication, reporting code, line, column and token class without echoing query text; function names, fields and semantics remain unchecked, and ambiguous syntax passes.
|
|
211
|
-
Rejected searches preserve redacted server diagnostics, completed searches include server warnings when present, and `search start --wait` advises when the normalized filter differs.
|
|
212
|
-
|
|
213
|
-
Vectra `host show` and `entity show --type host`, plus the matching raw host reads, retain every returned API field under `host`, separate from CLI metadata.
|
|
214
|
-
Use `--full` on host/entity detail commands for complete returned text; secret redaction still applies, and upstream omissions cannot be restored.
|
|
215
|
-
|
|
216
|
-
Vectra supports selected QUX/RUX writes for detection close/open and mark-fixed, host/account close, key assets, tags, notes (including bulk notes), assignments and outcomes, triage labels and rules, groups and membership, proxies, threat feeds, internal-network settings, syslog/Kafka, notification destinations and Match, subject to deployment support in the [reviewed inventory](tools/inventories/vectra-axi.json).
|
|
217
|
-
User, role, API-client and credential administration remains blocked.
|
|
218
|
-
Review the [Vectra grant warnings](docs/admin-guide.md#browser-administration) before enabling operations.
|
|
219
|
-
See [client input handling](docs/client-reference.md#command-surface-and-subcommands) for Vectra file inputs.
|
|
220
|
-
|
|
221
|
-
| Tool | Write capability and unlock |
|
|
222
|
-
| --- | --- |
|
|
223
|
-
| Falcon | Separate, off-by-default capabilities for guarded RTR execution and bounded MalQuery exact/fuzzy literal search. RTR retains the standard read-only command allowlist and profile narrowing. Host changes, scripts, hunt and file transfers remain unavailable. See [Falcon execution setup](docs/runbook.md#falcon-rtr-execution). |
|
|
224
|
-
| LDAP | Fixed read-only. |
|
|
225
|
-
| GitHub | Reviewed reads plus exact administrator-selected collaboration and repository writes, off by default, using classic or fine-grained PATs, admin-connected device-flow OAuth tokens or GitHub App installation tokens on GitHub.com, `*.ghe.com` or GHES. Artium previews each write without sending it; repeat the exact request with its returned `--confirm` value to execute. Installation tokens cannot access gists or user-only endpoints. Deletes, secret set, merge --admin, API non-GET, GraphQL escape paths, local git, setup/update, watch, downloads and local files stay blocked. Issue lock/unlock is unsupported by the pinned upstream combination; repo-edit visibility is unavailable. Only gist create/edit with `--filename` accepts stdin. Repository commands require `-R OWNER/NAME`; URL selectors and host-qualified repository names are refused. Repo creation requires a positional `OWNER/NAME`; project writes require `--owner OWNER` for recovery scope. Repo list/create, gist commands, search repos and api reject the `-R` selector. The bare dashboard and `home` remain refused because pinned gh-axi swallows dashboard read errors. SSH keys authenticate git transport, never the API used by gh-axi. See [GitHub setup](docs/tool-credentials.md#github) for the operation tiers, device flow and token lifecycle. |
|
|
226
|
-
| Azure | Reviewed resource mutations; administrator `allowWrites: true` plus native command gates. |
|
|
227
|
-
| Graph | Native mutations only with administrator `writes.allowWrites: true` and an explicit operations allow-list, plus native gates. |
|
|
228
|
-
| Vectra | Administrator `writes.allowWrites: true` and an explicit operations allow-list, native preview, `--execute`, exact `--confirm` and redacted journaling. Artium enforces the native read-only override while write access is off. |
|
|
229
|
-
| Azure DevOps | Reviewed mutations with administrator `allowWrites: true`; raw `api` remains GET-only. |
|
|
230
|
-
| AWX | Launch/cancel/relaunch, workflow approval/denial, project/inventory-source sync and notification tests with `allowWrites: true` and upstream `--confirm`; configuration, deletion and security writes stay blocked. |
|
|
231
|
-
| Tenable One | Business writes and export-job creation with administrator `writes.allowWrites: true`, an explicit operations allow-list, native preview, `--execute`, exact `--confirm` and durable journaling; downloads and local configuration stay blocked. |
|
|
232
|
-
| Check Point Email Security | Email and exception writes require administrator `writes.allowWrites: true`, exact selected operations and native preview, execute, confirmation and journal gates. Name-only event actions require their exact `event.action.<name>` scope. The six malware/URL/DLP remove/clear operations and click-time clear remain refused. Three separately selected downloads use [authenticated CLI saving](docs/client-reference.md#check-point-email-and-attachment-saving) with host-owned confirmation and independent SHA-256 verification; native download journal fields remain empty. Ordinary tool-run downloads and credential/origin overrides stay blocked. Live API contracts remain uncommissioned. |
|
|
233
|
-
| Hybrid Analysis | Sandbox submissions, YARA create/update/delete, consuming hunting matches and the four reviewed archive downloads require administrator `writes.allowWrites: true`, independently selected operations, native preview, `--execute`, exact `--confirm` and durable journaling. Downloads are limited to `hash-download-bin`, `report-download-bin`, `report-download-dropped-files` and `report-download-memory`, through the [authenticated CLI verified-save path](docs/client-reference.md#hybrid-analysis-archive-saving) after the [operator prerequisites](docs/runbook.md#scope-and-prerequisites) pass. All operations default off; enabling other writes never enables downloads or grants upstream entitlement. The browser provides warnings, command guidance and metadata/save status only. Ordinary tool-run downloads, local configuration and credential/origin overrides are blocked. |
|
|
234
|
-
|
|
235
|
-
Hybrid Analysis quick scans transmit the supplied sample or URL as read exceptions without a write gate; sandbox submission previews disclose that samples and reports can become visible to the community.
|
|
236
|
-
Consuming hunting matches is account-wide across all rules, with no rule selector, and irreversibly marks every returned match delivered; reconcile ambiguous outcomes using the audit ID, durable native journal and returned read-back guidance before retrying.
|
|
237
|
-
Updating a YARA rule with `reset_counter:true` resets its all-time match counter and changes its rule ID; use the returned ID for subsequent commands.
|
|
238
|
-
Labs hunting and search contracts are experimental.
|
|
239
|
-
|
|
240
|
-
There is no universal Artium confirmation flag.
|
|
241
|
-
Use authenticated tool help and the [write-access runbook](docs/runbook.md#roles-credentials-and-health) for operation-specific gates.
|
|
242
|
-
After an unknown write outcome, inspect state using returned guidance before retrying.
|
|
243
|
-
|
|
244
|
-
| Initial read | Required upstream permission |
|
|
245
|
-
| --- | --- |
|
|
246
|
-
| Falcon detections | `Alerts:read` |
|
|
247
|
-
| Vectra credential test | Health reads plus permissions for intended data |
|
|
248
|
-
| Azure subscription list | Application access to intended subscriptions; data-plane roles separately |
|
|
249
|
-
| Graph first-user read | Application `User.Read.All` with administrator consent |
|
|
250
|
-
| LDAP | Bind identity with directory read access |
|
|
251
|
-
| Azure DevOps project list | Identity permitted to view the organization/project |
|
|
252
|
-
| AWX job list | Token identity with job read access |
|
|
253
|
-
| Tenable One card list | See [Tenable One credential permissions](docs/tool-credentials.md#tenable-one). |
|
|
254
|
-
| Hybrid Analysis quota | A valid API key; resource permissions vary by key level. See [Hybrid Analysis setup](docs/tool-credentials.md#hybrid-analysis). |
|
|
255
|
-
| Check Point doctor | Regional authentication and one bounded email search. See [Check Point setup and commissioning](docs/tool-credentials.md#check-point-email-security). |
|
|
256
|
-
|
|
257
|
-
See [tool credentials](docs/tool-credentials.md) for dedicated identities, permissions and safe credential entry.
|
|
258
|
-
Artium stores shared service credentials encrypted with AES-256-GCM and never returns saved secrets to clients.
|
|
259
|
-
The data volume also holds the plaintext master key beside SQLite: protect the entire volume and keep offline escrow separate.
|
|
260
|
-
Linux client sessions use a mode-0700 directory and mode-0600 file under `${XDG_CONFIG_HOME:-~/.config}/artium-axi`.
|
|
261
|
-
Access tokens last one hour, with 12-hour local or 8-hour SSO CLI families; password changes revoke sessions.
|
|
262
|
-
|
|
263
|
-
Requests, bounded tool input and uploads travel to the server; enabled tools contact their upstream APIs using shared service identities.
|
|
264
|
-
Audit excludes injected credentials, request bodies, stdin, uploads and output streams.
|
|
265
|
-
The runner scans known secret encodings and discards output on a match; unknown upstream-minted tokens cannot be identified by exact-value scanning.
|
|
266
|
-
Its restricted environment, private directories and process limits are not a complete sandbox; descendants starting a new session can escape process-group termination.
|
|
89
|
+
Managed writes are off by default: administrator capability alone grants no tool access.
|
|
90
|
+
Enabled tools are read-only by default, with documented exceptions such as Hybrid Analysis quick scans that transmit samples or URLs.
|
|
91
|
+
There is no universal Artium confirmation flag or `ARTIUM_AXI_READ_ONLY` environment switch.
|
|
92
|
+
Administrators keep writes disabled or narrow operation allowlists; native gates can require preview, `--execute` and exact `--confirm`.
|
|
93
|
+
After an unknown outcome, inspect state before retrying.
|
|
94
|
+
Shared credentials are encrypted and never returned to clients; protect the entire data volume because it also holds the plaintext master key.
|
|
95
|
+
Client tokens are stored privately; never share session files or paste credentials into chat.
|
|
96
|
+
Linux client and Linux amd64 container paths have fake-service acceptance; Windows/macOS execution and agent-host loading remain unverified.
|
|
97
|
+
See [per-tool gates, storage and limits](docs/safety.md), [permissions](docs/tool-credentials.md), [deployment prerequisites](docs/runbook.md#scope-and-prerequisites) and [security boundaries](docs/admin-guide.md#security-and-acceptance-boundaries).
|
|
267
98
|
|
|
268
99
|
## Configuration
|
|
269
100
|
|
|
270
|
-
|
|
101
|
+
Connection settings are saved in `config.json` beside `session.json`; tool profiles and upstream credentials live on the server.
|
|
102
|
+
|
|
103
|
+
| Platform | Client configuration directory |
|
|
271
104
|
| --- | --- |
|
|
272
|
-
|
|
|
273
|
-
|
|
|
274
|
-
| `--password-stdin` | Login/new password via protected stdin |
|
|
275
|
-
| `--host`, `--hook`, `--force` | Setup host, optional Claude hook, explicit skill replacement |
|
|
276
|
-
| `--managed-session` | Caller-owned tokens through private pipes; see client reference |
|
|
277
|
-
| `--help`, `--version` | Local discovery without sign-in |
|
|
105
|
+
| Linux/macOS | `${XDG_CONFIG_HOME:-~/.config}/artium-axi` |
|
|
106
|
+
| Windows | `%APPDATA%\artium-axi` (execution unverified) |
|
|
278
107
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
108
|
+
| Client environment variable | Purpose | Default |
|
|
109
|
+
| --- | --- | --- |
|
|
110
|
+
| `ARTIUM_AXI_URL` | HTTPS server URL override | Saved URL; required initially |
|
|
111
|
+
| `ARTIUM_AXI_CA_FILE` | Additional PEM CA file | Saved CA path or Node trust |
|
|
112
|
+
| `ARTIUM_AXI_PASSWORD` | Ordinary login password, before terminal prompt | Unset; refused in managed mode |
|
|
113
|
+
| `ARTIUM_AXI_CURRENT_PASSWORD` | Ordinary password-change current password | Terminal prompt |
|
|
114
|
+
| `XDG_CONFIG_HOME` | Linux/macOS config base | `~/.config` |
|
|
115
|
+
| `APPDATA` | Windows config base | Required on Windows |
|
|
116
|
+
| `CLAUDE_CONFIG_DIR` | Claude setup directory | `~/.claude` |
|
|
117
|
+
| `PI_CODING_AGENT_DIR` | Pi setup directory | `~/.pi/agent` |
|
|
118
|
+
| `ARTIUM_AXI_TEST_HTTP` | Test-only loopback HTTP when `1` | Disabled |
|
|
119
|
+
| `ARTIUM_AXI_SESSION_ACL_PATH`, `ARTIUM_AXI_SESSION_ACL_KIND` | Internal Windows ACL subprocess inputs | Set by client; do not configure |
|
|
282
120
|
|
|
283
|
-
|
|
121
|
+
Prefer hidden password prompts or protected `--password-stdin`; clear password environment values after use.
|
|
122
|
+
See [client settings and refresh behavior](docs/client-reference.md#client-settings) and [server settings](docs/admin-guide.md#server-settings-and-custody) for the separate server environment and profile reference.
|
|
284
123
|
|
|
285
|
-
|
|
124
|
+
<a id="toon-output-and-errors"></a>
|
|
125
|
+
|
|
126
|
+
## Output and exit codes
|
|
286
127
|
|
|
287
|
-
| Command | Purpose |
|
|
288
|
-
| --- | --- |
|
|
289
|
-
| `artium-axi` | Identity, roles and available tools |
|
|
290
|
-
| `login --username <username>` / `login --sso` | Local password / browser approval |
|
|
291
|
-
| `passwd` / `logout` | Change password / remove local tokens and attempt revocation |
|
|
292
|
-
| `whoami` | Identity, roles, [session and access-token expiry](docs/client-reference.md#toon-output-behavior) and server |
|
|
293
|
-
| `tools` / `tools show <tool>` | Granted enabled tools / pinned help and first call |
|
|
294
|
-
| `doctor` | Server, TLS, token, version and cached health; five-second request deadlines |
|
|
295
|
-
| `update` | Update the [server-downloaded client](#verified-client) |
|
|
296
|
-
| `download` | Preview and explicitly verify/save administrator-selected Hybrid Analysis archives, Check Point emails/attachments and Graph mail exports through the local CLI. Run `artium-axi download --help` for guards and warnings. |
|
|
297
|
-
| `setup --host <host>` | Install managed skills and optional Claude hook |
|
|
298
|
-
| `<tool> <args>` | Run any of the ten managed tools above |
|
|
299
|
-
| `--managed-session --help` | Private-pipe session protocol |
|
|
300
|
-
|
|
301
|
-
`artium-axi --help falcon-axi` is local help; `artium-axi falcon-axi --help` authenticates and calls upstream.
|
|
302
|
-
The [full client reference](docs/client-reference.md#command-surface-and-subcommands) describes forwarding and supported input.
|
|
303
|
-
|
|
304
|
-
### TOON output and errors
|
|
305
128
|
Discovery and Artium errors use TOON on stdout; progress uses stderr.
|
|
306
129
|
Upstream stdout, stderr and exit status pass through, subject to managed suggestion adaptation and hosted status filtering.
|
|
307
|
-
Hosted
|
|
308
|
-
|
|
309
|
-
Artium exits 0 for success, 2 for usage/configuration errors and 1 for authentication/server/transport failures.
|
|
310
|
-
See the generated [error catalogue](docs/errors.md) for actionable codes and retry guidance.
|
|
130
|
+
Hosted status omits server paths and secret references expose only their source kind; malformed or truncated hosted status is withheld with `INVALID_RESPONSE`.
|
|
131
|
+
Tool output limits vary; `--full` restores supported text within byte/time budgets and secret redaction.
|
|
311
132
|
|
|
312
|
-
|
|
133
|
+
| Artium exit | Meaning |
|
|
134
|
+
| --- | --- |
|
|
135
|
+
| 0 | Success |
|
|
136
|
+
| 1 | Authentication, server or transport failure |
|
|
137
|
+
| 2 | Usage or configuration error |
|
|
138
|
+
|
|
139
|
+
See [output behavior](docs/client-reference.md#toon-output-behavior) and the generated [error catalogue](docs/errors.md).
|
|
140
|
+
|
|
141
|
+
## Troubleshooting
|
|
142
|
+
|
|
143
|
+
| Symptom | Next step |
|
|
144
|
+
| --- | --- |
|
|
145
|
+
| `CLIENT_CONFIG_INVALID` | Set the HTTPS URL and a readable CA file if needed, then sign in. |
|
|
146
|
+
| `PASSWORD_CHANGE_REQUIRED` | Run `artium-axi passwd`, then sign in again. |
|
|
147
|
+
| `CLI_OUTDATED` | Follow [installation-specific update guidance](docs/client-reference.md#verified-client). |
|
|
148
|
+
| No available tools | Ask an administrator to check enabled tools and role grants. |
|
|
149
|
+
| `CERTIFICATE_INVALID` | Check server TLS and the [private CA setup](docs/runbook.md#proxy-and-certificate-trust). |
|
|
313
150
|
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
See [adapter limits](docs/tool-credentials.md) and [deployment requirements](docs/runbook.md#scope-and-prerequisites).
|
|
151
|
+
<a id="verified-client"></a>
|
|
152
|
+
<a id="npm-client-alternative"></a>
|
|
153
|
+
<a id="build-from-source"></a>
|
|
154
|
+
<a id="platform-limits"></a>
|
|
155
|
+
|
|
156
|
+
Installation details live in the [client reference](docs/client-reference.md#verified-client), [source-build guide](CONTRIBUTING.md#build-from-source) and [platform limits](docs/runbook.md#platform-limits).
|
|
321
157
|
|
|
322
158
|
## Contributing
|
|
323
159
|
|
|
324
|
-
Use Linux and
|
|
325
|
-
|
|
160
|
+
Use Linux and follow [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
|
|
161
|
+
Development and release validation run locally through no-mistakes with fakes and synthetic identities; there is no hosted test CI.
|
|
162
|
+
|
|
163
|
+
## Security
|
|
164
|
+
|
|
165
|
+
See [SECURITY.md](SECURITY.md) for security boundaries and handling sensitive reports.
|
|
326
166
|
|
|
327
167
|
## License
|
|
328
168
|
|
|
329
169
|
[MIT](LICENSE).
|
|
330
|
-
|
|
331
|
-
If this project saved you time or helped your workflow, please consider giving it a ⭐ on GitHub to help others find it!
|