#167: Expose the passive auth surface tool

src/lib/tools/catalog.ts

@@ -77,6 +77,7 @@ const PROJECT_MUTATING_TOOL_IDS = new Set<string>([
   "negativeCoverageTool",
   "nucleiImportTool",
   "openApiImportTool",
+  "passiveAuthSurfaceTool",
   "patchLoopTool",
   "postmanImportTool",
   "proxyTrafficImportTool",
@@ -144,6 +145,7 @@ export const LOCAL_TOOL_IDS = [
   "negativeCoverageTool",
   "nucleiImportTool",
   "openApiImportTool",
+  "passiveAuthSurfaceTool",
   "patchLoopTool",
   "postmanImportTool",
   "productSkillRegistryTool",
@@ -406,6 +408,14 @@ const localToolOptions: RuntimeToolOption[] = [
     kind: "tool",
     risk: "passive",
   },
+  {
+    id: "tool:passiveAuthSurfaceTool",
+    label: "Passive auth surface",
+    description:
+      "Build a canonical authentication-surface report from authorized stored evidence without contacting the target.",
+    kind: "tool",
+    risk: "passive",
+  },
   {
     id: "tool:patchLoopTool",
     label: "Patch loop",
@@ -699,6 +709,7 @@ function resolveCapabilityControllerCategory(
 function resolveCapabilityStages(option: RuntimeToolOption): readonly SecurityCapabilityStage[] {
   const id = option.id.slice("tool:".length);
   if (id === "agentLabForegroundCommandTool") return [];
+  if (id === "passiveAuthSurfaceTool") return ["recon", "composition"];
   if (
     option.risk === "approval-gated" ||
     id === "approvalGateTool" ||

src/mastra/agents/security-research/stage-tools.ts

@@ -31,6 +31,7 @@ import { iocExportTool } from "../../tools/ioc-export";
 import { negativeCoverageTool } from "../../tools/negative-coverage";
 import { nucleiImportTool } from "../../tools/nuclei-import";
 import { openApiImportTool } from "../../tools/openapi-import";
+import { passiveAuthSurfaceTool } from "../../tools/passive-auth-surface";
 import { patchLoopTool } from "../../tools/patch-loop";
 import { postmanImportTool } from "../../tools/postman-import";
 import { productSkillRegistryTool } from "../../tools/product-skill-registry";
@@ -85,6 +86,7 @@ const stageToolRegistry = {
   negativeCoverageTool,
   nucleiImportTool,
   openApiImportTool,
+  passiveAuthSurfaceTool,
   patchLoopTool,
   postmanImportTool,
   productSkillRegistryTool,

src/mastra/tools/index.ts

@@ -23,6 +23,7 @@ export { iocExportTool } from "./ioc-export";
 export { negativeCoverageTool } from "./negative-coverage";
 export { nucleiImportTool } from "./nuclei-import";
 export { openApiImportTool } from "./openapi-import";
+export { passiveAuthSurfaceTool } from "./passive-auth-surface";
 export { patchLoopTool } from "./patch-loop";
 export { postmanImportTool } from "./postman-import";
 export { productSkillRegistryTool } from "./product-skill-registry";
@@ -79,6 +80,7 @@ import { iocExportTool } from "./ioc-export";
 import { negativeCoverageTool } from "./negative-coverage";
 import { nucleiImportTool } from "./nuclei-import";
 import { openApiImportTool } from "./openapi-import";
+import { passiveAuthSurfaceTool } from "./passive-auth-surface";
 import { patchLoopTool } from "./patch-loop";
 import { postmanImportTool } from "./postman-import";
 import { productSkillRegistryTool } from "./product-skill-registry";
@@ -132,6 +134,7 @@ export const securityResearchTools = {
   negativeCoverageTool,
   nucleiImportTool,
   openApiImportTool,
+  passiveAuthSurfaceTool,
   patchLoopTool,
   postmanImportTool,
   productSkillRegistryTool,

src/mastra/tools/passive-auth-surface.ts

@@ -0,0 +1,85 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+import { createStoredPassiveAuthSurface } from "../../server/recon/stored-passive-auth-surface";
+
+const storedArtifactRefSchema = z.object({
+	artifactId: z.string(),
+});
+
+export const passiveAuthSurfaceTool = createTool({
+	id: "security-passive-auth-surface",
+	description:
+		"Builds a canonical passive authentication-surface report from authorized, target-bound project artifacts. It does not contact the target or return raw evidence.",
+	inputSchema: z.object({
+		targetId: z.string(),
+		taskId: z.string().optional(),
+		artifacts: z.array(storedArtifactRefSchema),
+	}),
+	outputSchema: z.object({
+		status: z.literal("ok"),
+		targetId: z.string(),
+		taskId: z.string().optional(),
+		reportArtifactId: z.string(),
+		authorizationId: z.string(),
+		routeCategories: z.array(
+			z.object({
+				category: z.string(),
+				count: z.number(),
+				confidence: z.enum(["high", "medium"]),
+			}),
+		),
+		blockers: z.array(
+			z.object({
+				reason: z.string(),
+				evidenceArtifactIds: z.array(z.string()),
+			}),
+		),
+		unknowns: z.array(z.string()),
+		sourceArtifactIds: z.array(z.string()),
+	}),
+	execute: async (input, context) => {
+		const projectId = readContextString(
+			context.requestContext?.get("projectId"),
+		);
+		const threadId = readContextString(context.requestContext?.get("threadId"));
+		if (!projectId || !threadId) {
+			throw new Error(
+				"security-passive-auth-surface requires projectId and threadId in request context.",
+			);
+		}
+
+		const result = await createStoredPassiveAuthSurface({
+			projectId,
+			threadId,
+			targetId: input.targetId,
+			...(input.taskId ? { taskId: input.taskId } : {}),
+			artifacts: input.artifacts,
+		});
+
+		return {
+			status: "ok" as const,
+			targetId: input.targetId,
+			...(input.taskId ? { taskId: input.taskId } : {}),
+			reportArtifactId: result.artifact.id,
+			authorizationId: result.authorizationId,
+			routeCategories: result.summary.authRoutes.map((route) => ({
+				category: route.category,
+				count: route.urls.length,
+				confidence: route.confidence,
+			})),
+			blockers: result.summary.blockers.map((blocker) => ({
+				reason: blocker.reason,
+				evidenceArtifactIds: blocker.evidenceArtifactIds,
+			})),
+			unknowns: result.summary.unknowns,
+			sourceArtifactIds: result.sourceArtifacts.map(
+				(artifact) => artifact.artifactId,
+			),
+		};
+	},
+});
+
+function readContextString(value: unknown) {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}