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

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/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/parser.js

@@ -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.2"; // 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": "245e0b7b86311cb7876ef94dc3eab0550529501d14e25073516fad1c028c5552"
   },
   "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.2",
   "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.
 ```