@shieldaai/agent-map 0.1.0-alpha.2 → 1.0.0

package/dist/service/operations/get-resource-access.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** One host-bound resource, the agents mapped to it, and what reaches it outside the guard. */
+export declare const getResourceAccess: Operation;

package/dist/service/operations/get-resource-access.js

@@ -0,0 +1,48 @@
+import { fail } from '../../common.js';
+import { sourceSelection } from '../context.js';
+import { ordered, page } from '../ordering.js';
+import { boundedReach, directAccess, OUTSIDE_GUARD_LIMITATION } from '../outside-guard.js';
+import { agentSummary, collection, findSource, focus, receipt, resourceSummary } from '../summaries.js';
+import { matching, string } from '../work.js';
+/** One host-bound resource, the agents mapped to it, and what reaches it outside the guard. */
+export const getResourceAccess = {
+    request: args => ({ ...sourceSelection(args), outsideGuard: true, policy: false }),
+    run({ scope, args, work, maxBytes }, view) {
+        const source = findSource(view, args.sourceId), projection = source.current;
+        const resource = projection.nodes.find(node => node.label === 'GuardResourceBinding' && matching(node, args.resourceId, 'binding_id'));
+        if (!resource)
+            fail('MAP_NOT_FOUND');
+        const agents = ordered(projection.nodes
+            .filter(node => node.label === 'GuardAgent')
+            .filter(agent => {
+            work.step();
+            return focus(projection, agent, work).nodes.some(node => node.id === resource.id);
+        })
+            .map(agent => agentSummary(source, projection, agent, work)));
+        const { items, ...pagination } = page(agents, args);
+        const reach = boundedReach(work.remaining(), maxBytes)(projection, resource, scope, true);
+        return {
+            data: {
+                resource: resourceSummary(source, projection, resource, work),
+                agents: items,
+                ...pagination,
+                outsideGuard: {
+                    status: reach.status,
+                    directAccess: reach.directAccess,
+                    directAccessTruncated: reach.directAccessTruncated,
+                    identities: reach.identities,
+                    identitiesTruncated: reach.identitiesTruncated,
+                    unknownReasons: reach.unknownReasons,
+                    evidenceKind: 'declared',
+                },
+                receipt: receipt(source),
+                assessment: 'unknown',
+                collection,
+                limitations: [
+                    'Agents have a declared selector mapped to this resource; this is not proof of current effective access.',
+                    OUTSIDE_GUARD_LIMITATION,
+                ],
+            },
+        };
+    },
+};

package/dist/service/operations/list-agents.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** The agent index, optionally filtered by boundary flag or carrying each row's flag. */
+export declare const listAgents: Operation;

package/dist/service/operations/list-agents.js

@@ -0,0 +1,92 @@
+import { dangerousThree } from '../../boundary-flags.js';
+import { fail } from '../../common.js';
+import { MapQueryError } from '../../types.js';
+import { sourceSelection } from '../context.js';
+import { agentFlags } from '../flags.js';
+import { agentSortKey, page, sortedBy } from '../ordering.js';
+import { agentSummary } from '../summaries.js';
+import { QueryWork, string } from '../work.js';
+/** The agent index, optionally filtered by boundary flag or carrying each row's flag. */
+export const listAgents = {
+    request(args) {
+        // `flag` lists flagged agents; asking it for the absent ones is a contradiction.
+        if (args.flag !== undefined && args.flagStatus === 'absent')
+            fail('MAP_REQUEST_INVALID');
+        return {
+            ...sourceSelection(args),
+            // Filtering by flag needs every agent's flags; showing them needs only the page's.
+            ...(args.flag !== undefined || args.flagStatus !== undefined ? { flags: true } : { summary: true }),
+        };
+    },
+    async run({ scope, args, work, maxBytes, read }, view) {
+        const search = typeof args.search === 'string' ? args.search.toLocaleLowerCase('en-US') : '';
+        const filtered = args.flag !== undefined || args.flagStatus !== undefined;
+        const statuses = args.flagStatus !== undefined
+            ? [args.flagStatus]
+            : args.flag !== undefined
+                ? ['exposed', 'mitigated', 'unknown']
+                : ['exposed', 'mitigated', 'unknown', 'absent'];
+        const agents = view.sources
+            .flatMap(source => {
+            work.step(source.current.nodes.length);
+            return source.current.nodes
+                .filter(node => node.label === 'GuardAgent')
+                .flatMap(agent => {
+                const summary = agentSummary(source, source.current, agent, work);
+                if (!filtered)
+                    return [summary];
+                const status = agentFlags(source.current, agent, scope, work).status;
+                return statuses.includes(status) ? [{ ...summary, boundaryFlags: { dangerousThree: status } }] : [];
+            });
+        })
+            .filter(agent => (!search ||
+            [agent.name, agent.agentId].some(value => typeof value === 'string' && value.toLocaleLowerCase('en-US').includes(search))) &&
+            (args.ownerId === undefined || agent.ownerId === args.ownerId) &&
+            (args.teamId === undefined || agent.teamId === args.teamId) &&
+            (args.ownershipStatus === undefined || agent.ownershipStatus === args.ownershipStatus) &&
+            (args.lifecycleState === undefined || agent.lifecycleState === args.lifecycleState) &&
+            (args.environment === undefined ||
+                agent.environments.includes(args.environment)));
+        // Unnamed agents sort last; code-point order keeps paging identical on every host and locale.
+        sortedBy(agents, agentSortKey);
+        const { items, ...pagination } = page(agents, args);
+        let rows = items;
+        let flagsUnavailable = null;
+        if (args.includeFlags === true && !filtered && rows.length) {
+            // Flags for this page only: one read of these agents under the one-agent rules, so a
+            // badge here matches get_agent_access and the work follows the page, not the fleet.
+            // If that read is too large or fails, the listing still answers, with every flag unknown.
+            // The page flags get what is left of this query's time, keep a margin for the answer,
+            // and count their work separately: running out degrades flags, not the listing.
+            const budget = work.remaining() - 50;
+            const found = new Map();
+            try {
+                if (budget <= 0)
+                    fail('MAP_TIMEOUT');
+                const flagged = await read({ ...sourceSelection(args), flags: true, agentIds: rows.map(agent => agent.id) }, budget);
+                const flagWork = new QueryWork(Math.max(1, work.remaining() - 25), maxBytes);
+                for (const agent of rows) {
+                    const source = flagged.sources.find(item => item.id === agent.sourceId);
+                    const node = source?.current.nodes.find(item => item.label === 'GuardAgent' && item.entityId === agent.id);
+                    // An agent gone between the two reads has no evidence now.
+                    if (source && node)
+                        found.set(agent, agentFlags(source.current, node, scope, flagWork).status);
+                }
+            }
+            catch (error) {
+                const code = error instanceof MapQueryError ? error.code : 'MAP_UNAVAILABLE';
+                if (!['MAP_LIMIT_EXCEEDED', 'MAP_TIMEOUT', 'MAP_UNAVAILABLE'].includes(code))
+                    throw error;
+                found.clear();
+                flagsUnavailable =
+                    code === 'MAP_LIMIT_EXCEEDED'
+                        ? 'flags_limit_exceeded'
+                        : code === 'MAP_TIMEOUT'
+                            ? 'flags_timeout'
+                            : 'flags_read_unavailable';
+            }
+            rows = rows.map(agent => ({ ...agent, boundaryFlags: { dangerousThree: found.get(agent) ?? 'unknown' } }));
+        }
+        return { data: { agents: rows, ...pagination, ...(flagsUnavailable ? { flagsUnavailable } : {}) } };
+    },
+};

package/dist/service/operations/list-owners-resources.d.ts

@@ -0,0 +1,5 @@
+import { type Operation } from '../context.js';
+/** Owners and teams, with how many visible agents and resources each one owns. */
+export declare const listOwners: Operation;
+/** Host-bound resources, each with whether something reaches it outside the guard. */
+export declare const listResources: Operation;

package/dist/service/operations/list-owners-resources.js

@@ -0,0 +1,69 @@
+import { sourceSelection } from '../context.js';
+import { ordered, page } from '../ordering.js';
+import { boundedReach, OUTSIDE_GUARD_LIMITATION } from '../outside-guard.js';
+import { ownerSummary, resourceSummary } from '../summaries.js';
+import { string } from '../work.js';
+const matches = (item, search) => !search ||
+    [item.name, item.displayName, item.ownerId, item.bindingId, item.resourceRef].some(value => typeof value === 'string' && value.toLocaleLowerCase('en-US').includes(search));
+const searchText = (args) => typeof args.search === 'string' ? args.search.toLocaleLowerCase('en-US') : '';
+/** Owners and teams, with how many visible agents and resources each one owns. */
+export const listOwners = {
+    request: args => ({ ...sourceSelection(args), owners: true }),
+    run({ args, work }, view) {
+        const search = searchText(args);
+        const rows = ordered(view.sources
+            .flatMap(source => {
+            work.step(source.current.nodes.length);
+            return source.current.nodes
+                .filter(node => node.label === 'GuardOwner')
+                .map(node => ownerSummary(source, source.current, node, work));
+        })
+            .filter(item => matches(item, search) && (args.kind === undefined || item.kind === args.kind)));
+        const { items, ...pagination } = page(rows, args);
+        return { data: { owners: items, ...pagination } };
+    },
+};
+/** Host-bound resources, each with whether something reaches it outside the guard. */
+export const listResources = {
+    // Policy evidence is read only where it is returned: a listing asks for none, so the store's
+    // 512-pair policy limit does not bound it.
+    request: args => ({ ...sourceSelection(args), outsideGuard: true, policy: false }),
+    run({ scope, args, work, maxBytes }, view) {
+        const search = searchText(args);
+        // Where each resource row came from, so reach can be judged after paging.
+        const origins = new Map();
+        const rows = ordered(view.sources
+            .flatMap(source => {
+            work.step(source.current.nodes.length);
+            return source.current.nodes
+                .filter(node => node.label === 'GuardResourceBinding')
+                .map(node => {
+                const summary = resourceSummary(source, source.current, node, work);
+                origins.set(summary, { projection: source.current, node });
+                return summary;
+            });
+        })
+            .filter(item => matches(item, search) &&
+            (args.ownerId === undefined || item.ownerId === args.ownerId) &&
+            (args.sensitivity === undefined || item.sensitivity === args.sensitivity)));
+        const { items, ...pagination } = page(rows, args);
+        // Reach is judged for the returned page only: its budget is never spent on rows the
+        // caller does not see, and a filter or a later page costs no more than its own rows.
+        const reach = boundedReach(work.remaining(), maxBytes);
+        const resources = items.map(item => {
+            const origin = origins.get(item);
+            return { ...item, outsideGuard: reach(origin.projection, origin.node, scope).status };
+        });
+        return {
+            data: {
+                resources,
+                ...pagination,
+                resourceCoverage: 'host_bound_resources',
+                limitations: [
+                    'Declared selectors without a host resource binding are not included; see agent permissions.',
+                    OUTSIDE_GUARD_LIMITATION,
+                ],
+            },
+        };
+    },
+};

package/dist/service/ordering.d.ts

@@ -0,0 +1,9 @@
+import type { JsonObject, JsonValue } from '../types.js';
+export declare const compare: (a: string, b: string) => number;
+export declare const sortText: (value: JsonValue | undefined) => string;
+export declare function compareSortKeys(a: readonly string[], b: readonly string[]): number;
+/** Sorts in place by precomputed keys: each row's key is built once, not once per comparison. */
+export declare function sortedBy<T extends object>(items: T[], key: (item: T) => readonly string[]): T[];
+export declare const agentSortKey: (agent: JsonObject) => readonly string[];
+export declare function ordered(items: JsonObject[]): JsonObject[];
+export declare function page(items: readonly JsonObject[], args: Readonly<Record<string, JsonValue>>): JsonObject;

package/dist/service/ordering.js

@@ -0,0 +1,47 @@
+import { compareCodePoints } from '../common.js';
+import { number, string } from './work.js';
+export const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+// Sort keys compare field by field in Unicode code-point order, so "Reader" comes before
+// "Reader 2" and paging is identical on every host and locale. Equal names fall back to the
+// source and the stable id.
+export const sortText = (value) => typeof value === 'string' ? value : value === null || value === undefined ? '' : JSON.stringify(value);
+export function compareSortKeys(a, b) {
+    for (let index = 0; index < a.length; index++) {
+        const order = compareCodePoints(a[index], b[index]);
+        if (order)
+            return order;
+    }
+    return 0;
+}
+/** Sorts in place by precomputed keys: each row's key is built once, not once per comparison. */
+export function sortedBy(items, key) {
+    const keys = new Map(items.map(item => [item, key(item)]));
+    return items.sort((a, b) => compareSortKeys(keys.get(a), keys.get(b)));
+}
+// Unnamed agents sort last.
+export const agentSortKey = (agent) => [
+    agent.name === null || agent.name === undefined ? '1' : '0',
+    sortText(agent.name),
+    sortText(agent.sourceId),
+    sortText(agent.id),
+];
+export function ordered(items) {
+    return sortedBy(items, item => [
+        sortText(item.name ?? item.displayName),
+        sortText(item.sourceId),
+        sortText(item.id ?? item.entityId),
+        sortText(item.source),
+        sortText(item.target),
+        sortText(item.kind),
+    ]);
+}
+export function page(items, args) {
+    const offset = args.offset ?? 0, limit = args.limit ?? 50;
+    return {
+        items: items.slice(offset, offset + limit),
+        total: items.length,
+        offset,
+        limit,
+        truncated: offset + limit < items.length,
+    };
+}

package/dist/service/outside-guard.d.ts

@@ -0,0 +1,68 @@
+import { type JsonObject, type MapIdentityExtraResource, type MapIdentityScope, type MapNode, type MapProjection, type ReadScope } from '../types.js';
+import { type FocusedGraph } from './summaries.js';
+import { QueryWork } from './work.js';
+/** A declared target names a host resource; name it only when that resource is in the reader's scope. */
+export declare function targetVisibility(projection: MapProjection, scope: ReadScope, work: QueryWork): (target: string) => boolean;
+/**
+ * Host-declared paths that act without the guard, per deployment in the agent's focus.
+ * Manifest v3 sets `direct_access_status`; older manifests leave it absent, which reads as
+ * `unknown` and never as `none_declared`.
+ */
+export declare function directAccess(projection: MapProjection, graph: FocusedGraph, scope: ReadScope, work: QueryWork): JsonObject[];
+/** `data` with each identity-scope list cut to `keep` entries, or null if nothing would change. */
+export declare function shortenIdentityScope(data: JsonObject, keep: number): JsonObject | null;
+export type Reach = 'yes' | 'none_found' | 'unknown';
+export interface ReachIndex {
+    readonly undeclaredDeployments: number;
+    /** Declared paths without a target, such as a shell, can touch any resource. */
+    readonly untargetedPaths: number;
+    /** Declared paths whose target matches no resource in this read (perhaps another team's). */
+    readonly unresolvedPaths: number;
+    /** Visible granted tools with no declared execution identity (ambient or unknown). */
+    readonly undeclaredIdentities: number;
+    readonly directByTarget: Map<string, MapNode[]>;
+    readonly identitiesByBucket: Map<string, {
+        record: MapIdentityScope;
+        extra: MapIdentityExtraResource;
+    }[]>;
+    readonly identityUnknown: number;
+    readonly identityCollected: boolean;
+    /** AWS accounts of the evaluated identities; a bucket elsewhere was never compared. */
+    readonly identityAccounts: ReadonlySet<string | null>;
+}
+export declare const reachIndex: WeakMap<MapProjection, ReachIndex>;
+/**
+ * Outside-guard reach over the whole visible projection: any declared direct path or any
+ * evaluated tool identity can touch any resource, so `none_found` needs every visible
+ * deployment to have declared its paths and every visible identity to be evaluated.
+ */
+export declare function outsideGuardIndex(projection: MapProjection, work: QueryWork): ReachIndex;
+/** Entries listed per resource in get_resource_access before the list is marked truncated. */
+export declare const REACH_LIST_LIMIT = 100;
+export interface ReachResult {
+    status: Reach;
+    unknownReasons: string[];
+    directAccess: JsonObject[];
+    directAccessTruncated: boolean;
+    identities: JsonObject[];
+    identitiesTruncated: boolean;
+}
+/**
+ * `detail` builds the (bounded) lists for one resource; the listing only needs the status,
+ * which comes from index lookups.
+ */
+export declare function outsideGuardReach(projection: MapProjection, resource: MapNode, scope: ReadScope, work: QueryWork, detail?: boolean): ReachResult;
+/**
+ * Reach with its own work budget, shared by every row of one response: if it runs out, that
+ * row and every later one read `unknown` (`reach_not_evaluated`) and the response still
+ * answers. Rows judged before that keep their status: each used a complete index.
+ */
+export declare function boundedReach(remaining: number, maxBytes: number): (projection: MapProjection, resource: MapNode, scope: ReadScope, detail?: boolean) => ReachResult;
+export declare const OUTSIDE_GUARD_LIMITATION = "Only S3 identity policies and host declarations of this source are checked, within your visible scope; none_found is not proof that no path exists.";
+/**
+ * C2 per execution binding in the agent's focus. A store that did not run the reverse identity
+ * read reports every binding as `unknown` rather than leaving it out.
+ */
+export declare function identityScope(projection: MapProjection, graph: {
+    nodes: MapNode[];
+}): JsonObject[];