@knowttl/artium-axi 0.0.6 → 0.0.7

package/README.md

@@ -14,7 +14,7 @@ Administrators manage accounts, roles, encrypted service credentials and audit r
 The client follows AXI (Agent eXperience Interface) conventions for discovery, help and structured errors.
 
 **Status: under construction.**
-Falcon, Vectra, Azure, Graph, LDAP and Azure DevOps are wired into the production server entry point.
+Falcon, Vectra, Azure, Graph, LDAP, Azure DevOps and AWX are wired into the production server entry point.
 See the [evidence ledger](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/evidence-ledger.md) for the acceptance boundaries.
 
 ## Agent Ergonomics
@@ -209,7 +209,8 @@ The [credential standard](docs/credential-standard.md#9-hosted-contract-artium-a
 | Azure (`az-axi`) | Entra tenant ID, application client ID, client secret or certificate private key and SHA-256 thumbprint, subscription IDs and optional workspace mapping. | `account list`; data-plane roles need their own permitted reads. |
 | Microsoft Graph (`mg-axi`) | Entra tenant ID, application client ID, client secret or certificate private key and SHA-256 thumbprint, administrator-consented Graph application permissions. | `entra user list --limit 1`; other domains need their own permissions. |
 | LDAP (`ldap-axi`) | Verified LDAPS or StartTLS URL, read-only bind identity and password, optional search base and private CA PEM. | `auth status`; binds once and reports the selected identity. |
-| Azure DevOps (`ado-axi`) | Organization, optional default project and personal access token (PAT). | `project list --limit 1`. |
+| Azure DevOps (`ado-axi`) | Organization, optional default project and either a PAT or tenant ID, client ID and client secret. | `project list --limit 1`. |
+| AWX (`awx-axi`) | Controller HTTPS origin and an existing personal access token. | `job list --limit 1`; job read permissions are required. |
 
 #### Falcon
 
@@ -217,10 +218,12 @@ In the Falcon console, open **Support and resources > API clients and keys** and
 Copy its client ID and secret and record its cloud region: `us-1`, `us-2`, `eu-1` or `us-gov-1`.
 At `/admin/tools/falcon-axi`, enter `clientId`, `clientSecret` and `region`, with `memberCid` only when targeting a Flight Control member tenant.
 Grant `Alerts:read` for detection reads, including the first-call example.
-Grant additional scopes only for the domains you use, following the pinned [API client permission matrix](https://github.com/knowttl/falcon-axi/blob/v0.3.0/README.md#api-client-permissions) and its offline `scopes` command.
+Grant additional scopes only for the domains you use, following the pinned [API client permission matrix](https://github.com/knowttl/falcon-axi/blob/v0.5.0/README.md#api-client-permissions) and its offline `scopes` command.
 For example, account reads need `Assets:read`, while CVE reads need `Vulnerabilities (Falcon Intelligence):read`, distinct from Spotlight vulnerability access.
 NG-SIEM search requires `NGSIEM:write`; Identity Protection directory/timeline queries require `Identity Protection GraphQL:write` plus the documented read scopes, even though those queries read data.
 These are optional domain requirements and do not justify granting other write or response scopes.
+The pinned tool does not change hosts, detections, policies or identities and exposes no arbitrary REST or GraphQL requests.
+Starting and stopping NG-SIEM search jobs are its only tenant-side effects; these investigation operations remain available regardless of the saved write switch.
 Falcon's fixed `auth status` test reports local credential resolution, so also run `artium-axi falcon-axi detection list --limit 1` after enabling and granting the tool.
 
 #### Vectra
@@ -231,7 +234,7 @@ QUX OAuth requires appliance release 9.1 or later; `applianceRelease` is optiona
 For RUX, select `kind=rux`, `apiVersion=3.4`, `auth=oauth`, `clientId` and `clientSecret`; leave `applianceRelease` blank.
 Create a QUX personal token under **My Profile** using a local account, or have a Vectra administrator create an OAuth API client under **Manage > API Clients** and record the displayed ID and secret.
 Tokens inherit their user's rights and clients inherit their assigned role; grant read access to health and the Hosts, Accounts, Detections or other areas you need.
-See [Vectra's credential issuance guidance](https://github.com/vectranetworks/vectraautomatedresponse#getting-a-vectra-api-token-for-vectra-detect-api-v2) and the pinned [Vectra configuration contract](https://github.com/knowttl/vectra-axi/tree/v0.1.5#configuration) for deployment-specific requirements.
+See [Vectra's credential issuance guidance](https://github.com/vectranetworks/vectraautomatedresponse#getting-a-vectra-api-token-for-vectra-detect-api-v2) and the pinned [Vectra configuration contract](https://github.com/knowttl/vectra-axi/tree/v0.1.7#configuration) for deployment-specific requirements.
 For a credential-specific private CA, paste its PEM contents into `caBundle`; enter no server file path.
 For shared trust across tools, follow the [private CA runbook](docs/runbook.md#tls-inspection-and-private-upstream-cas).
 Keep Native settings empty for read-only use; optional writes need the native operation allowlist and upstream permissions.
@@ -318,7 +321,7 @@ Delegated permissions and interactive `User.Read` consent do not authorize this
 | Identity providers | `IdentityProvider.Read.All` |
 | Lifecycle workflows | `LifecycleWorkflows.Read.All` |
 
-For other domains, use the pinned [Graph access and licence guidance](https://github.com/knowttl/mg-axi/blob/v0.1.7/docs/graph-coverage.md) and the command's permission requirements rather than granting every permission.
+For other domains, use the pinned [Graph access and licence guidance](https://github.com/knowttl/mg-axi/blob/v0.1.10/docs/graph-coverage.md) and the command's permission requirements rather than granting every permission.
 Licences still apply: PIM and risk/governance features can fail despite consent, and some commands support only delegated identities.
 Do not add `User.Export.All` just to make a read-only setup pass; data-policy export is a write-class permission.
 
@@ -353,6 +356,8 @@ Enter the password itself in the form, never a SecretRef or password-file path.
 Save, run **Test credential**, enable the tool, grant it to a role, then run `artium-axi ldap-axi user list --limit 1` to check directory read permissions.
 **Test credential** runs `auth status`, which performs one bind; failed credentials can count toward directory account lockout limits.
 LDAP is read-only by design and has no editable native write settings.
+LDAP 0.2.0 adds `computer list`, `computer show <identifier-or-dn>` and `server` reads through the same managed identity.
+Computer reads use AD machine accounts or the upstream's stated LDAPv3 device fallback; `server` reports advertised rootDSE capabilities and limits.
 The [LDAP inventory](tools/inventories/ldap-axi.json) owns the supported commands, blocked overrides and resource requirements.
 Local fake-directory and offline profile checks do not establish live directory acceptance.
 
@@ -365,6 +370,10 @@ Artium encrypts the PAT in its credential store and injects it through a private
 Do not enter a SecretRef or environment-variable name.
 Create a dedicated PAT scoped to the organization with Work Items, Code and Build read permissions as needed for the commands you use.
 Grant corresponding read-write permissions only for intended mutations; a write switch never grants Azure DevOps permissions.
+For service principal authentication, choose `auth=client-secret` and enter `tenantId`, `clientId` and `clientSecret` instead of `token`.
+Add the service principal as a user in the Azure DevOps organization, in the organization's Entra tenant, and grant the required project permissions before testing.
+Artium acquires and caches an Azure DevOps access token with client credentials and supplies it through a restricted per-call `az` stand-in.
+The stand-in answers only the pinned tool's Azure DevOps token request; no Azure CLI sign-in or device flow is used.
 Save, run **Test credential**, enable the tool, grant it to a role, then run `artium-axi ado-axi project list --limit 1`.
 
 Writes are off by default; follow [write-access administration](docs/runbook.md#roles-credentials-and-health) to enable them.
@@ -376,9 +385,31 @@ All commands refuse repeated flags, stdin and files.
 Use `pipeline watch --timeout 50` or less to stay within the runner's call timeout.
 Writes are journaled by Artium only; see [audit action classification](#audit-screen-and-api).
 For an interrupted write, run the returned read-back command and follow its inspection guidance before retrying.
-PAT authentication is available now; client ID and secret authentication is a separate integration phase, with no device flow.
 Local fake-service checks do not establish live organization acceptance.
 
+#### AWX
+
+Artium bundles the [pinned](tools/package.json) `awx-axi` package without upstream modifications.
+At `/admin/tools/awx-axi`, enter the controller HTTPS `origin` and paste an existing personal access token into `token`.
+Enter the token itself, never a SecretRef, environment-variable name, password or file path.
+Artium encrypts the token and injects a SecretRef through its private per-call profile; it does not mint or revoke AWX tokens.
+Save, run **Test credential**, enable the tool and grant it to a role, then run `artium-axi awx-axi job list --limit 1`.
+**Test credential** reads one job using the managed token and reports structured authentication, network and TLS diagnostics.
+For a private certificate, inspect and trust it through the tool page; trust is scoped to the saved credential and host.
+HTTP and TLS-verification bypasses are refused.
+
+Writes are off by default.
+The native setting `{"allowWrites": true}` permits only operational writes, which still require upstream `--confirm`: launching, canceling or relaunching runs, approving or denying workflow approvals, project and inventory-source syncs, and notification-template tests.
+Configuration writes, deletes and security writes are always blocked, including resource creation and editing, associations, role grants and token operations.
+Artium never enables AWX's separate configuration, deletion or security write gates.
+Token permissions remain an additional AWX-side limit; the write switch does not grant AWX permissions.
+The generated [AWX inventory](tools/inventories/awx-axi.json) classifies every command and records the reviewed upstream source digests.
+Artium manages origin, TLS and credential selectors, and refuses standalone auth login/logout, setup, config, profile and update commands.
+Stdin, file uploads, server file paths and `@file` values are unsupported; use inline non-secret launch parameters.
+Use `job watch --timeout 50` or less to stay within the runner timeout.
+For an interrupted write, inspect current state using the returned read-back guidance before retrying.
+Local fake-service checks do not establish live controller acceptance.
+
 ### Build from source
 
 The source toolchain requires Node **24.11 or later** and **pnpm 10.22.0**.
@@ -434,7 +465,8 @@ artium-axi falcon-axi --help
 
 The first prints local Artium help without signing in or contacting the server.
 The second forwards `--help` through the authenticated upstream adapter.
-A bare Falcon or Vectra invocation shows upstream help; `artium-axi az-axi` and `artium-axi az-axi home` run the Azure dashboard with ARM authentication.
+A bare `artium-axi falcon-axi` reads recent detections; use `artium-axi falcon-axi --help` for its command list.
+A bare Vectra invocation shows upstream help; `artium-axi az-axi` and `artium-axi az-axi home` run the Azure dashboard with ARM authentication.
 A bare `artium-axi ldap-axi` shows directory discovery with managed-credential guidance.
 Arguments after a tool name belong to upstream, subject to adapter restrictions on credential, configuration and file paths.
 Unknown Azure flags return `INVALID_INPUT` with the flag name, valid flags and a hosted help command.
@@ -461,7 +493,7 @@ Details read bundled manifests and stored health without fetching credentials or
 Discovery and administration show the server's bundled tool versions, as defined by the [API contract](src/shared/api.ts).
 
 Upstream calls preserve stdout, stderr and nonzero exit codes.
-For Falcon, Vectra, Azure, Graph, LDAP and Azure DevOps, recognized TOON or JSON root `help` suggestions, plain upstream help and bundled tool-detail help use `artium-axi <tool>` commands, including examples originally invoking `npx -y @knowttl/<tool>`.
+For Falcon, Vectra, Azure, Graph, LDAP, Azure DevOps and AWX, recognized TOON or JSON root `help` suggestions, plain upstream help and bundled tool-detail help use `artium-axi <tool>` commands, including examples originally invoking `npx -y @knowttl/<tool>`.
 Recognized flag listings and command suggestions omit managed flags declared in each pinned [tool inventory](tools/inventories/)'s `unsafeOverrides`, including Graph profile, config and scopes selectors.
 LDAP home output lists hosted commands, and recognized connection and TLS recovery hints direct callers to an administrator to update the [stored LDAP credentials](#ldap).
 Unrelated content, literal argument values, unknown formats and truncated streams remain unchanged.
@@ -515,6 +547,10 @@ The last enabled administrator cannot be disabled, demoted or archived.
 Profile, role and archive changes use revision checks; reload stale forms rather than overwriting newer changes.
 Session revocation and administration changes commit with their audit records.
 After 15 minutes without identity confirmation, administration mutations require reauthentication.
+After a tool credential test fails TLS verification, an administrator can inspect its saved endpoint’s certificate and trust it for that credential in one confirmation.
+The UI shows full fingerprints, warnings, expiry and removable trust; hostname and validity verification remain enabled.
+A missing intermediate is fetched automatically only when its chain reaches an already-trusted root.
+See [credential certificate trust](docs/runbook.md#trusting-one-tool-from-the-administration-ui) for inspection, rotation and the network-path warning.
 Administration and account screens share a navigation menu.
 Signed-in screens have a header showing identity, sign-in source and sign-out.
 On administration screens, the header also shows the remaining confirmation window.
@@ -556,7 +592,7 @@ The form exposes the schema's full requirements, including conditional requireme
 Azure uses guided source-identity fields because the host brokers resource tokens separately.
 Azure and Graph certificate editors accept one PEM file containing one certificate and its matching unencrypted private key and calculate the fingerprint automatically.
 See the [hosted contract](docs/credential-standard.md#9-hosted-contract-artium-axi) for profile injection.
-Falcon has guided fields even when its pinned package has no credential schema; its injection path stays unchanged.
+Falcon has guided fields; see its [current credential handling](docs/credential-standard.md#per-tool-host-facing-schemas).
 Browser saves keep native settings and retain blank stored secrets for the same identity.
 Identity changes require new secrets as defined by the [credential-save contract](src/shared/api.ts) (`adminToolRoutes.save`).
 Select **Test after saving** to save and report a harmless credential check inline.
@@ -680,7 +716,7 @@ Device approval and refusal emit `device-approve` and `device-deny` events, with
 Each `run-terminal` record uses `action` to report `write` when the native tool journal contains valid JSON object records for that run, or `read` when a successful run leaves its supported journal absent or empty.
 This records journal activity, including mutation intents, rather than guaranteeing that a remote change succeeded.
 Pinned Falcon and LDAP runs report `read` from their inventories' read-only declarations, including normal runs and health checks.
-ADO uses host classification: reads report `read`, successful write calls report `write`, and failed or interrupted writes report `unknown`.
+ADO and AWX use host classification: reads report `read`, successful write calls report `write`, and failed or interrupted writes report `unknown`.
 For tools with native journals, failures without journal records and malformed or unreadable evidence report `unknown`; recovered interrupted runs also report `unknown`.
 See the [API contract](src/shared/api.ts) and [retention and export runbook](docs/runbook.md#retention-and-export).