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

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/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);

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

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

package/artium-invocations.json

@@ -8,7 +8,7 @@
   },
   "parser": {
     "path": ".typescript-build/src/parser.js",
-    "sha256": "245e0b7b86311cb7876ef94dc3eab0550529501d14e25073516fad1c028c5552"
+    "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.2",
+  "version": "1.0.0-rc.3",
   "private": false,
   "type": "module",
   "license": "MIT",