@knowttl/falcon-axi 1.0.0-rc.1 → 1.0.0-rc.3

package/.typescript-build/src/auth.js

@@ -9,6 +9,18 @@ export function responseFailure(response, subject, token = false, member = false
     const envelope = object(response.body) ? response.body : {};
     const meta = object(envelope.meta) ? envelope.meta : {};
     const details = typeof meta.trace_id === "string" ? { trace_id: meta.trace_id } : {};
+    const requestHelp = operationId === "RTRAuditSessions"
+        ? [
+            `Check that the API client has ${scopes.join(" and ")} in the Falcon console under Support and resources > API clients and keys; run \`falcon-axi scopes\` for the matrix`,
+            "This rejection does not confirm a missing scope; if the scope is granted, report the request command and trace_id to CrowdStrike support",
+        ]
+        : operationId === "GetSearchStatusV1"
+            ? [
+                "A stopped or expired job may no longer be queryable; this rejection does not confirm that the job was stopped",
+                "Check the job identifier and pass the same `--repository` the job was started against",
+                "Run `falcon-axi search start --query '<cql>'` to start a new job if needed",
+            ]
+            : undefined;
     if (response.status === 400) {
         if (operationId === "api_preempt_proxy_post_graphql")
             throw new CliError("UPSTREAM_ERROR", `Falcon rejected falcon-axi's fixed Identity Protection query for ${subject}`, [
@@ -86,15 +98,16 @@ export function responseFailure(response, subject, token = false, member = false
                 ? ["host list", "hostname:'WIN-*'"]
                 : ["detection list", "severity_name:'High'+status:'new'"]);
         const errors = Array.isArray(envelope.errors) ? envelope.errors : [];
-        if (errors.some((error) => object(error) &&
-            typeof error.message === "string" &&
-            /\b(fql|filter|query)\b/i.test(error.message)))
+        if (operationId !== "GetSearchStatusV1" &&
+            errors.some((error) => object(error) &&
+                typeof error.message === "string" &&
+                /\b(fql|filter|query)\b/i.test(error.message)))
             throw new CliError("FQL_INVALID", `the filter for ${subject} was rejected`, [
                 "FQL uses + for AND, `,` for OR, and values must be quoted",
                 `Example: \`--filter "${example}"\``,
                 `Run \`falcon-axi ${command} --help\` for the filterable fields`,
             ]);
-        throw new CliError("UPSTREAM_ERROR", `Falcon rejected the request for ${subject}`, ["Check the flags for this command with `--help`"], details);
+        throw new CliError("UPSTREAM_ERROR", `Falcon rejected the request for ${subject}`, requestHelp ?? ["Check the flags for this command with `--help`"], details);
     }
     if (response.status === 401)
         throw new CliError("AUTH_FAILED", "the Falcon credential was rejected", [
@@ -162,6 +175,7 @@ export function responseFailure(response, subject, token = false, member = false
     throw new CliError("UPSTREAM_ERROR", `Falcon could not answer the request for ${subject}`, [
         "Retry shortly",
         "Quote the trace_id when opening a CrowdStrike support case",
+        ...(requestHelp ?? []),
     ], details);
 }
 export function observeRate(session, response) {

package/.typescript-build/src/cli.js

@@ -62,6 +62,8 @@ export async function main(argv, bin) {
                 .map((name) => ` --${name}`)
                 .join("");
         const result = help.map((item) => item.replace(/`(falcon-axi .*)`/s, (_, command) => `\`${command}${suffix}\``));
+        if (help.some((item) => item.includes("<original-filter>")))
+            result.push("Replace <original-filter> with your original --filter value when continuing; CID filters are not echoed");
         if (memberCid && help.some((item) => /`falcon-axi /.test(item)))
             result.push("Supply the same tenant selection used for this invocation when following these suggestions");
         return result;

package/.typescript-build/src/core.js

@@ -17,15 +17,32 @@ export class CliError extends Error {
 export function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-// Preserve numeric lexemes outside Number's exact integer domain before rounding.
+// Preserve numeric lexemes outside Number's exact integer domain, judged from the
+// original text because JSON.parse has already rounded the value it hands us.
 export function parseResponse(text) {
     return JSON.parse(text, (_key, value, context) => {
-        if (typeof value !== "number" ||
-            Math.abs(value) <= Number.MAX_SAFE_INTEGER ||
-            !context?.source)
+        if (typeof value !== "number" || !context?.source)
             return value;
-        return /^-?\d+$/.test(context.source)
-            ? BigInt(context.source)
-            : context.source;
+        const { source } = context;
+        if (/^-?\d+$/.test(source)) {
+            const integer = BigInt(source);
+            return (integer < 0n ? -integer : integer) >
+                BigInt(Number.MAX_SAFE_INTEGER)
+                ? integer
+                : value;
+        }
+        const [mantissa, exponent = "0"] = source.replace(/^-/, "").split(/[eE]/);
+        const [whole, fraction = ""] = mantissa.split(".");
+        const coefficient = whole + fraction;
+        const significant = coefficient.replace(/^0+/, "");
+        if (!significant)
+            return value;
+        const position = BigInt(whole.length - (coefficient.length - significant.length)) +
+            BigInt(exponent);
+        const digits = significant.replace(/0+$/, "");
+        return position > 16n ||
+            (position === 16n && digits.padEnd(16, "0") > "9007199254740991")
+            ? source
+            : value;
     });
 }

package/.typescript-build/src/cursor.js

@@ -63,3 +63,10 @@ export class Cursor {
         }
     }
 }
+// Serializes a cursor query context exactly as Python's json.dumps did: ASCII-only
+// output with either compact or default separators, so existing tokens stay valid.
+export function pythonJson(value, compact = false) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => pythonJson(item, compact)).join(compact ? "," : ", ")}]`;
+    return JSON.stringify(value).replace(/[\u007f-\uffff]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}

package/.typescript-build/src/domain.js

@@ -1,4 +1,5 @@
 import { CliError, object } from "./core.js";
+import { recoveryHelp } from "./metadata.js";
 import { responseFailure } from "./auth.js";
 import { requestRead } from "./transport/https.js";
 import { malformed } from "./response.js";
@@ -36,13 +37,14 @@ export class Domain {
     async response(operation, subject, query = {}, body, missing = false) {
         const response = await requestRead(operation, this.session.base, this.session.token, query, body, this.allowUnknown, this.signal);
         if (response.status === 404 && !missing) {
-            const noun = this.invocation.command.name.startsWith("identity sensor ")
-                ? "identity sensor"
-                : this.invocation.command.name.split(" ")[0];
-            throw new CliError("NOT_FOUND", noun === "host-group"
+            const { command, flags } = this.invocation;
+            const hostGroup = command.name.startsWith("host-group ");
+            throw new CliError("NOT_FOUND", hostGroup
                 ? "no host group matched that identifier"
                 : `no ${subject} matched that identifier`, [
-                `Run \`falcon-axi ${noun} list${noun === "policy" ? ` --type ${this.invocation.flags.get("--type")}` : ""}\`${noun === "host-group" ? "" : " to see current identifiers"}`,
+                hostGroup
+                    ? "Run `falcon-axi host-group list`"
+                    : recoveryHelp(command.name, flags),
             ]);
         }
         if (response.status === 403 &&

package/.typescript-build/src/executable.js

@@ -1,5 +1,5 @@
-import { realpathSync, statSync, accessSync, constants } from "node:fs";
-import { dirname, isAbsolute, join, resolve, sep, delimiter } from "node:path";
+import { realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
 import { CliError } from "./core.js";
 export function shellArgument(value) {
     return process.platform === "win32"
@@ -12,23 +12,6 @@ export function executableCommand(hook = false) {
     const name = hook ? "falcon-axi-hook" : "falcon-axi";
     if (!statSync(target).isFile())
         throw new CliError("CONFIG_INVALID", `cannot locate ${name}; reinstall falcon-axi`);
-    // npm's Windows .cmd wrapper is a shell script, so use Node plus its entry point.
-    if (hook && process.platform !== "win32")
-        for (const directory of (process.env.PATH ?? "").split(delimiter)) {
-            const candidate = join(directory || ".", name);
-            try {
-                accessSync(candidate, constants.X_OK);
-                if (!statSync(candidate).isFile())
-                    continue;
-                if (isAbsolute(directory) && realpathSync(candidate) === target)
-                    return [name];
-                break;
-            }
-            catch (error) {
-                if (!["ENOENT", "ENOTDIR", "EACCES", "ELOOP"].includes(error.code ?? ""))
-                    throw error;
-            }
-        }
     return [process.execPath, target];
 }
 export function durableInstallation() {

package/.typescript-build/src/help.json

@@ -10,7 +10,7 @@
     "detection show": "falcon-axi detection show <composite id> [--full]\n\n--full       print long fields such as the command line without truncation\n\nExample: falcon-axi detection show \"ldt:aid:1234\"\n\nThis command is read-only and requires only Alerts:read.",
     "detection process": "falcon-axi detection process <composite id> [--full]\n\n--full       print command lines without the default 800-character truncation\n\nShow the triggering process, parent, and grandparent recorded on the alert.\nRows contain relation, filename, filepath, cmdline, sha256, and process_id.\ntriggering_process_graph_id is the alert's graph pivot; this view does not fetch a graph.\nAbsent ancestors and alerts without a process are stated explicitly.\nExamples:\n  falcon-axi detection process 'ldt:synthetic-agent:1001'\n  falcon-axi detection process 'ldt:synthetic-agent:1001' --full\n\nThis command is read-only and requires only Alerts:read.",
     "host list": "falcon-axi host list [--hostname <name>] [--platform <name>] [--status <name>] [--since <window>] [--filter <FQL>] [--limit N] [--cursor <token>] [--all] [--max-rows N] [--fields <names>]\n\n--hostname   hostname to match; Hosts filters accept wildcards, so WIN-* works\n--platform   one of windows, mac, linux\n--status     one of normal, containment_pending, contained, lift_containment_pending\n--since      last_seen within a relative window such as 24h or 7d\n--filter     raw FQL; + is AND, `,` is OR, values are single-quoted, relative dates are lowercase\n--limit      rows in this call (default 20, ceiling 5000)\n--cursor     opaque continuation token from a previous call\n--all        walk pages; page size is independent of --limit\n--max-rows   row budget (default 1000; requires --all)\n--fields     extra columns, comma-separated: os_version, agent_version, status, first_seen, machine_domain\n\nFilterable fields include hostname, platform_name, os_version, agent_version, status,\nlast_seen, first_seen, machine_domain, and local_ip.\nExamples:\n  falcon-axi host list --platform windows --since 24h\n  falcon-axi host list --filter \"hostname:'WIN-*'+platform_name:'Windows'\"\n\nThis command is read-only and requires only Hosts:read. It reports containment status as\ndata and cannot change it.",
-    "host show": "falcon-axi host show <device id>\n\nThe device id is the agent id Falcon calls the AID, as printed by `falcon-axi host list`.\n\nExample: falcon-axi host show abc123\n\nThis command is read-only and requires only Hosts:read.",
+    "host show": "falcon-axi host show <device id>\n\nThe device id is the agent id Falcon calls the AID, as printed by `falcon-axi host list`.\n\nExample: falcon-axi host show 0123456789abcdef0123456789abcdef\n\nThis command is read-only and requires only Hosts:read.",
     "host logins": "falcon-axi host logins <device id> [--since <window>] [--limit N]\nfalcon-axi host logins --hostname <pattern> [--since <window>] [--limit N]\n\nThe device id is the agent id Falcon calls the AID, as printed by `falcon-axi host list`.\n--hostname   match a hostname (wildcards allowed), instead of a device id; requires exactly one match\n--since      window to read, such as 24h or 7d (default 7d, Falcon's own default)\n--limit      logins per host in this call (default 20, ceiling 100)\n\nReports recent interactive logins from the Host Timeline as device_id, user_name, and\nlogin_time. It is a window, not a full audit trail: a host that returns its limit may have more.\nExample: falcon-axi host logins abc123 --since 24h\nExample: falcon-axi host logins --hostname 'synthetic-host-*' --since 24h --limit 2\nHostname form: one lookup capped at 2 IDs, then one history read; 60s total deadline.\nAmbiguous or incomplete lookups fail without reading history; upstream partial errors are disclosed.\n\nThis command is read-only and requires only Hosts:read.",
     "host network": "falcon-axi host network <device id>\nfalcon-axi host network --hostname <pattern>\n\nRetrieves the IP and MAC address history Falcon retains for one sensor host.\nThe device id is the AID printed by `falcon-axi host list`.\n--hostname   match a hostname (wildcards allowed), instead of a device id; requires exactly one match\nExample: falcon-axi host network abc123\nExample: falcon-axi host network --hostname 'synthetic-host-*'\nHostname form: one lookup capped at 2 IDs, then one history read; 60s total deadline.\nAmbiguous or incomplete lookups fail without reading history; upstream partial errors are disclosed.\nRead-only; requires Hosts:read. This endpoint has no pagination parameters.",
     "ioc list": "falcon-axi ioc list [--filter <FQL>] [--limit N] [--cursor <token>]\n\n--filter  FQL on type, value, action, source, severity_number, expired, created_on, modified_on\n--limit   rows per call (default 20, ceiling 500)\n--cursor  opaque continuation token\n\nExamples:\n  falcon-axi ioc list --filter \"type:'domain'+expired:false\"\n  falcon-axi ioc list --limit 100\n\nRead-only; requires IOC Management:read.",

package/.typescript-build/src/identity.js

@@ -1,4 +1,5 @@
 import { CliError, object } from "./core.js";
+import { pythonJson } from "./cursor.js";
 import { Domain, text } from "./domain.js";
 import { Raw } from "./render.js";
 import { seconds } from "./search.js";
@@ -208,12 +209,12 @@ export async function identity(domain) {
     const type = flags.get("--type")?.toLowerCase();
     const fingerprint = timeline
         ? [entityId(id).toLowerCase(), since.toLowerCase(), chosen.join(",")].join("|")
-        : JSON.stringify([
+        : pythonJson([
             type ?? null,
             flags.get("--name") ?? null,
             flags.get("--email") ?? null,
             flags.get("--domain") ?? null,
-        ]);
+        ], true);
     const context = domain.cursor("api_preempt_proxy_post_graphql", fingerprint, "token");
     const variables = { first: limit };
     let start = new Date(Date.now() - seconds(since) * 1000)

package/.typescript-build/src/inspection.js

@@ -1,4 +1,6 @@
 import { CliError, object } from "./core.js";
+import { pythonJson } from "./cursor.js";
+import { recoveryHelp } from "./metadata.js";
 import { Domain, count, more, project, text } from "./domain.js";
 import { Raw, redact, truncate } from "./render.js";
 import { operation } from "./transport/operations.js";
@@ -330,7 +332,7 @@ export async function inspection(domain, filter) {
                 ]
                 : ["classification", "data-policy"].includes(noun)
                     ? [`Run \`falcon-axi ${noun} list --help\` to find identifiers`]
-                    : []);
+                    : [recoveryHelp(command.name, flags)]);
         const record = records[0];
         if (recon || collection)
             return detail(domain, recon ? "record" : collectionNoun.replaceAll(" ", "_"), record, true, recon ? "for untruncated content" : "for untruncated detail");
@@ -378,9 +380,9 @@ export async function inspection(domain, filter) {
         filter = sandboxFilter(flags);
     const sort = noun === "indicator" ? "_marker.asc" : flags.get("--sort");
     const contextFilter = data
-        ? JSON.stringify([filter ?? null, flags.get("--platform") ?? null])
+        ? pythonJson([filter ?? null, flags.get("--platform") ?? null], true)
         : noun === "policy"
-            ? JSON.stringify([filter ?? null, members ? id : null])
+            ? pythonJson([filter ?? null, members ? id : null], true)
             : filter;
     const context = domain.cursor(op, contextFilter, noun === "indicator" ? "marker" : (collection?.model ?? "offset"), sort ?? null);
     const position = supplied

package/.typescript-build/src/inventory.js

@@ -1,4 +1,5 @@
 import { CliError, object } from "./core.js";
+import { pythonJson } from "./cursor.js";
 import { Domain, count, ids, more, project, quote, text } from "./domain.js";
 import { Raw, redact, truncate } from "./render.js";
 export const applicationFields = [
@@ -167,7 +168,7 @@ export async function inventory(domain, filter) {
     if (noun === "host-group") {
         const members = name.endsWith("members");
         const sort = members ? null : "name.asc";
-        const context = domain.cursor(operation, `[${JSON.stringify(id ? [id] : [])}, ${JSON.stringify(filter ?? null)}]`.replace(/[\u007f-\uffff]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`), "offset", sort);
+        const context = domain.cursor(operation, pythonJson([id ? [id] : [], filter ?? null]), "offset", sort);
         const position = flags.has("--cursor")
             ? Number(context.decode(flags.get("--cursor")))
             : 0;

package/.typescript-build/src/investigation.js

@@ -1,10 +1,11 @@
 import { CliError, object } from "./core.js";
-import { Cursor } from "./cursor.js";
+import { Cursor, pythonJson } from "./cursor.js";
 import { Raw, redact, truncate } from "./render.js";
 import { requestRead } from "./transport/https.js";
 import { responseFailure } from "./auth.js";
 import { malformed } from "./response.js";
 import { text, quote, project } from "./domain.js";
+import { recoveryHelp } from "./metadata.js";
 const invalid = (message, details = {}) => {
     throw new CliError("UPSTREAM_ERROR", message, [], details);
 };
@@ -94,21 +95,18 @@ export async function investigate(invocation, credential, session, filter, allow
                 ]);
             if (name.startsWith("ioc "))
                 throw new CliError("NOT_FOUND", "no IOC record matched that identifier", ["Run `falcon-axi ioc list`"]);
-            const command = operation === "QueryGetNetworkAddressHistoryV1"
-                ? "host list"
-                : name.startsWith("file-change ")
-                    ? "file-change list"
-                    : name.startsWith("rtr session ")
-                        ? "rtr session list"
-                        : name.startsWith("rtr audit ")
-                            ? "rtr audit list"
-                            : "detection list";
             throw new CliError("NOT_FOUND", `no ${subject} matched that identifier`, [
-                `Run \`falcon-axi ${command}\` to see current identifiers`,
+                recoveryHelp(name === "home" ? "detection list" : name, flags),
             ]);
         }
         if (response.status !== 200)
             responseFailure(response, subject, false, false, operation);
+        if ((name === "host logins" || name === "host network") &&
+            Array.isArray(envelope.errors) &&
+            envelope.errors.length)
+            invalid(operation === "QueryDevicesByFilter"
+                ? "Falcon returned a partial hostname lookup; history was not read"
+                : `Falcon returned partial host ${name === "host logins" ? "login" : "network"} history`, { partial: true });
         const rows = Array.isArray(response.body)
             ? response.body
             : envelope.resources;
@@ -272,8 +270,6 @@ export async function investigate(invocation, credential, session, filter, allow
         if (more && offset < wall) {
             value.continuation_cursor = context.encode(offset);
             help.push(`Run \`${suggestion} --cursor ${String(value.continuation_cursor)}\` for the next page`);
-            if (filter && /\b(?:cid|member_cid)\s*:/i.test(filter))
-                help.push("Replace <original-filter> with your original --filter value when continuing; CID filters are not echoed");
         }
         else if (more)
             help.push(wallHelp[0], hosts
@@ -662,7 +658,7 @@ export async function investigate(invocation, credential, session, filter, allow
         const type = id.slice(0, id.indexOf(":"));
         const indicator = id.slice(id.indexOf(":") + 1);
         const host = flags.get("--host");
-        const context = cursor(operation, JSON.stringify([type, indicator, host ?? null]).replaceAll(",", ", "));
+        const context = cursor(operation, pythonJson([type, indicator, host ?? null]));
         const offset = flags.has("--cursor")
             ? context.decode(flags.get("--cursor"))
             : 0;

package/.typescript-build/src/malquery.js

@@ -1,5 +1,6 @@
 import { CliError, object } from "./core.js";
 import { Domain, project } from "./domain.js";
+import { recoveryHelp } from "./metadata.js";
 import { Raw } from "./render.js";
 import { searchBody } from "./transport/search-authority.js";
 import { requestException, requestRead } from "./transport/https.js";
@@ -37,7 +38,15 @@ export async function malquery(domain) {
             "Check `falcon-axi malquery search --help` for the supported literal pattern grammar",
         ]);
     if (response.status === 404)
-        throw new CliError("NOT_FOUND", `no ${metadata ? "MalQuery metadata" : status || submit ? "MalQuery search" : "MalQuery quota"} matched that identifier`, ["Run `falcon-axi malquery quota` to see current identifiers"]);
+        throw new CliError("NOT_FOUND", `no ${metadata ? "MalQuery metadata" : status || submit ? "MalQuery search" : "MalQuery quota"} matched that identifier`, metadata || status || submit
+            ? [
+                recoveryHelp(metadata
+                    ? "malquery show"
+                    : status
+                        ? "malquery status"
+                        : "malquery search", new Map()),
+            ]
+            : []);
     if (response.status !== 200)
         responseFailure(response, metadata
             ? "MalQuery metadata"

package/.typescript-build/src/metadata.js

@@ -550,6 +550,35 @@ export const boolFlags = [
     "--no-member-cid",
 ];
 export const commandNames = commands.map((command) => command.name);
+// Recovery guidance for an identifier or collection that Falcon did not find.
+// Commands whose list needs a selector the failed command may not carry point
+// to that list's help instead of an invalid invocation.
+export const recoveryHelp = (name, flags, kind) => {
+    if (name.startsWith("process "))
+        return "Run `falcon-axi ioc processes <type:value> --host <device_id>` to find process identifiers";
+    if (name === "malquery search")
+        return "Run `falcon-axi malquery search --help` for the supported literal pattern grammar";
+    if (name === "malquery status")
+        return "Run `falcon-axi malquery search --help` to start a search and obtain a request identifier";
+    if (name === "malquery show")
+        return "Run `falcon-axi malquery show --help` for the SHA-256 argument it expects";
+    const words = name.split(" ");
+    const collection = name === "rtr run"
+        ? "host list"
+        : words.at(-1) === "list"
+            ? name
+            : words.length === 3
+                ? `${words[0]} ${words[1]} list`
+                : `${words[0]} list`;
+    const selector = { exclusion: "type", policy: "type", "data-policy": "platform" }[words[0]];
+    const value = selector ? flags.get(`--${selector}`) : undefined;
+    const command = value !== undefined && /^[A-Za-z0-9_-]+$/.test(value)
+        ? `${collection} --${selector} ${value}`
+        : selector || ["sandbox", "serverless", "vuln"].includes(words[0])
+            ? `${collection} --help`
+            : collection;
+    return `Run \`falcon-axi ${command}\` to ${command.endsWith(" --help") ? "see the selectors it requires" : kind === "policy" ? "find policy ids" : `see current ${kind ? `${kind} ` : ""}identifiers`}`;
+};
 for (const flag of [
     ...valueFlags,
     ...boolFlags,

package/.typescript-build/src/parser.js

@@ -1,5 +1,5 @@
 import { CliError } from "./core.js";
-import { commands, valueFlags, boolFlags } from "./metadata.js";
+import { commands, valueFlags, boolFlags, recoveryHelp } from "./metadata.js";
 import { applicationFields } from "./inventory.js";
 import { shieldFilters } from "./exposure.js";
 import { validateInspection } from "./inspection.js";
@@ -98,21 +98,21 @@ export function parse(argv) {
         if (command.positional &&
             (hostname ? positionals.length !== 0 : positionals.length !== 1))
             throw new CliError("VALIDATION_ERROR", `${command.name} requires exactly one ${command.positional}`, [
-                command.name === "policy members"
-                    ? "Run `falcon-axi policy list --type prevention` to find policy ids"
-                    : command.name === "cve show"
-                        ? "A CVE identifier matches CVE-<year>-<number>, for example CVE-2021-44228"
-                        : command.name === "vuln show"
-                            ? "Run `falcon-axi vuln list --status open` to find Spotlight record identifiers"
-                            : command.name.startsWith("search ")
-                                ? "A search identifier comes from `falcon-axi search start --query '<cql>'`"
-                                : ["identity show", "identity timeline"].includes(command.name)
-                                    ? "Run `falcon-axi identity list` to see current identity ids"
-                                    : command.name === "identity activity"
-                                        ? "Run `falcon-axi detection show <id>` for an identity detection's account_id"
-                                        : command.name === "identity sensor show"
-                                            ? "Run `falcon-axi identity sensor list` to see current sensor identifiers"
-                                            : `Run \`falcon-axi ${command.name.startsWith("host ") ? "host" : command.name.startsWith("detection ") ? "detection" : command.name.split(" ")[0]} list\` to see current ${command.name.startsWith("host ") ? "device" : command.name.split(" ")[0]} identifiers`,
+                command.name === "cve show"
+                    ? "A CVE identifier matches CVE-<year>-<number>, for example CVE-2021-44228"
+                    : command.name === "vuln show"
+                        ? "Run `falcon-axi vuln list --status open` to find Spotlight record identifiers"
+                        : command.name.startsWith("search ")
+                            ? "A search identifier comes from `falcon-axi search start --query '<cql>'`"
+                            : ["identity show", "identity timeline"].includes(command.name)
+                                ? "Run `falcon-axi identity list` to see current identity ids"
+                                : command.name === "identity activity"
+                                    ? "Run `falcon-axi detection show <id>` for an identity detection's account_id"
+                                    : command.name === "identity sensor show"
+                                        ? "Run `falcon-axi identity sensor list` to see current sensor identifiers"
+                                        : recoveryHelp(command.name, flags, command.name.startsWith("host ")
+                                            ? "device"
+                                            : command.name.split(" ")[0]),
             ]);
         if (!command.positional && positionals.length)
             throw new CliError("VALIDATION_ERROR", `\`${command.name}\` accepts no positional arguments`, valid);
@@ -150,6 +150,10 @@ export function parse(argv) {
             throw new CliError("VALIDATION_ERROR", "--max-rows must be a positive integer");
     }
     const id = positionals[0];
+    if (command.name === "host show" &&
+        id &&
+        (!/^[a-fA-F0-9]{32}$/.test(id) || /^0{32}$/.test(id)))
+        throw new CliError("VALIDATION_ERROR", "host show requires a nonzero 32-character hexadecimal device id (AID)", ["Run `falcon-axi host list` to see current device identifiers"]);
     if (!flags.has("--help"))
         validateInspection(command.name, flags, limit);
     if (command.name === "cve show" && id && !/^CVE-[0-9]{4}-[0-9]{4,}$/.test(id))

package/.typescript-build/src/rtr.js

@@ -95,7 +95,7 @@ export async function rtrRun(invocation, credential, base, cancelled) {
     const policy = credential.rtr ?? rtrPolicy(undefined);
     const commandBase = parseRtr(command, policy.commands);
     if (executing && (credential.channel !== "file" || !policy.enabled))
-        throw new CliError("READ_ONLY_VIOLATION", "RTR execution requires explicit profile opt-in");
+        throw new CliError("READ_ONLY_VIOLATION", "RTR execution requires explicit profile opt-in", ['Set "rtr": {"enabled": true} on the selected file profile']);
     if (executing && (process.platform !== "linux" || process.arch !== "x64"))
         throw new CliError("CONFIG_INSECURE", "RTR execution requires a supported POSIX controller");
     process.stdout.write(render({

package/.typescript-build/src/search.js

@@ -116,7 +116,7 @@ export async function search(domain) {
         return {
             value: { stopped: id, repository },
             help: [
-                `Run \`${follow("status")}\` to confirm the job reports cancelled`,
+                "A stopped job may no longer be queryable with `falcon-axi search status`",
                 "Run `falcon-axi search start --query '<cql>'` to run a narrower search",
             ],
         };

package/.typescript-build/src/version.js

@@ -1 +1 @@
-export const VERSION = "1.0.0-rc.1";
+export const VERSION = "1.0.0-rc.3"; // x-release-please-version

package/README.md

@@ -131,7 +131,7 @@ Run `falcon-axi config path` to inspect config and journal paths.
 | `FALCON_AXI_WRITE_LOG` | Mandatory RTR execution journal | State directory `writes.log` |
 | `XDG_CONFIG_HOME`, `XDG_STATE_HOME` | Absolute POSIX config / state roots | `~/.config`, `~/.local/state` |
 | `APPDATA`, `LOCALAPPDATA` | Windows config / state roots | `~/AppData/Roaming`, `~/AppData/Local` |
-| `HOME`, `PATH` | Home and hook executable discovery | Process environment / OS home |
+| `HOME` | Home directory for session integrations | OS home directory |
 | `CLAUDECODE`, `CODEX_THREAD_ID`, `CODEX_SESSION_ID`, `PI_CODING_AGENT`, `OPENCODE` | Detect the host for skill-install hints | Unset |
 | `CLAUDE_CONFIG_DIR`, `PI_CODING_AGENT_DIR` | Host skill-discovery roots | `~/.claude`, `~/.pi/agent` |
 | `FALCON_CLIENT_ID`, `FALCON_CLIENT_SECRET`, `FALCON_MEMBER_CID`, `FALCON_BASE_URL`, `FALCON_PROXY_URL` | Deprecated aliases; replacements win | Unset |

package/artium-invocations.json

@@ -8,7 +8,7 @@
   },
   "parser": {
     "path": ".typescript-build/src/parser.js",
-    "sha256": "19fc9b9145604071e06b790992dedfa9c09a162aac18dbf00ffd8184e003f1ca"
+    "sha256": "1a348bb4a13e0034d5919b218e02ddf7ed0036b51d78d06b488bda4fcb78f8eb"
   },
   "skill": {
     "path": "skills/falcon-axi/SKILL.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/falcon-axi",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "private": false,
   "type": "module",
   "license": "MIT",

package/skills/falcon-axi/references/agent-guide.md

@@ -18,7 +18,7 @@ Do not allow a whole noun such as `host` or `search`: other subcommands can crea
 | Alert detail: `detection show <id>` | `falcon-axi detection show 'ldt:synthetic-agent-01:1001' --full` | `--full` removes long-field previews |
 | Alert process lineage: `detection process <id>` | `falcon-axi detection process 'ldt:synthetic-agent:1001'` | Trigger, parent, grandparent, hashes and graph pivot in one call; `--full` removes 800-character command-line previews |
 | Find host: `host list` | `falcon-axi host list --hostname 'synthetic-host-*' --limit 2 --fields status,os_version,agent_version` | `--platform windows`, `--since 24h`, `--filter <FQL>`; returns device IDs (AIDs) |
-| Host detail: `host show <device-id>` | `falcon-axi host show synthetic-device-01` | Full host record; no `--full` flag |
+| Host detail: `host show <device-id>` | `falcon-axi host show 00000000000000000000000000000001` | Full host record; no `--full` flag |
 | Host address history: `host network <device-id>` | `falcon-axi host network synthetic-device-01` | Retained IP/MAC history; no pagination or time flag |
 | Interactive logins: `host logins <device-id>` | `falcon-axi host logins synthetic-device-01 --since 24h --limit 2` | Default window 7d; default 20, maximum 100 logins; a filled window may omit older logins |
 | Graph lineage: `process tree <pid-id>` | `falcon-axi process tree pid:synthetic-device:1` | Up to five ancestors and one child level, 100 child edges per page; `--cursor <token>` continues children; `--full` for complete command lines |

package/skills/falcon-axi/references/host-show.md

@@ -7,7 +7,7 @@ npx -y @knowttl/falcon-axi@next host show <device id>
 
 The device id is the agent id Falcon calls the AID, as printed by `npx -y @knowttl/falcon-axi@next host list`.
 
-Example: npx -y @knowttl/falcon-axi@next host show abc123
+Example: npx -y @knowttl/falcon-axi@next host show 0123456789abcdef0123456789abcdef
 
 This command is read-only and requires only Hosts:read.
 ```