@cdxgen/cdxgen 13.5.0 → 13.7.0

package/lib/inventory/agentBlueprint.js

@@ -0,0 +1,193 @@
+/**
+ * Declared coding-agent behaviour at CycloneDX 2.0 (cdxgen/cdxgen#4593).
+ *
+ * The source is the AI inventory the 1.x parsers already produce
+ * (communityAiConfigParser: Kiro agents, Claude subagents and agent
+ * definitions). Only real agent definitions count: a component with a
+ * `cdx:agent:role`, or whose `cdx:file:kind` is `agent-definition` or
+ * `claude-subagent`. Instruction files, specs, steering documents, agent
+ * configs and plugins describe or configure agents but are not agents.
+ * At 2.0 this module derives:
+ *
+ * - one party per agent component with a bom-ref
+ *   (#/$defs/cyclonedx-party-2.0/$defs/party, role `agent`) whose `system`
+ *   (#/$defs/cyclonedx-party-2.0/$defs/system) has kind `agent`, `ref` the
+ *   agent component's refId, `label` its name and `permissions` the tool
+ *   names its config allows. The allow list is split on the commas outside
+ *   parentheses, and each entry is reduced to the tool name before any "("
+ *   (`Bash(git status:*)` is `Bash`), so arguments, paths and commands
+ *   never reach the BOM. Names that are not safe tool names are dropped
+ *   (see lib/inventory/agentToolNames.js). The list is unique and sorted.
+ *
+ * - one blueprint (#/$defs/cyclonedx-blueprint-2.0/$defs/blueprint,
+ *   modelTypes `behavioral`) whose actors reference the agent parties and
+ *   whose behaviors.instances carry `acknowledgment: ["declared"]` and a
+ *   `behavior` from data/behavior-taxonomy.schema.json:
+ *   `ai:agent:invokesTool` when the agent declares tools or MCP servers, and
+ *   `ai:agent:requestsUserApproval` when its permission policy has ask rules.
+ *   The inventory records only how many MCP servers an agent's own config
+ *   names, not which, so instances carry no `targets`: naming the project's
+ *   MCP services would claim a binding no config makes.
+ *
+ * No free text from instruction, skill or MCP files is emitted. Business
+ * objectives and use cases are free text, so they are out of scope, and so
+ * is observed behaviour.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { dirNameStr } from "../core/paths.js";
+import { agentToolName, splitAllowList } from "./agentToolNames.js";
+
+/** refId of the derived blueprint. */
+export const AGENT_BLUEPRINT_REF_ID = "blueprint-declared-agents";
+/** Prefix of every derived agent party refId. */
+export const AGENT_PARTY_REF_ID_PREFIX = "party-agent-";
+
+const AGENT_ROLE_PROPERTY = "cdx:agent:role";
+const AGENT_DEFINITION_FILE_KINDS = new Set([
+  "agent-definition",
+  "claude-subagent",
+]);
+const BEHAVIOR_TAXONOMY = new Set(
+  JSON.parse(
+    readFileSync(
+      join(dirNameStr, "data", "behavior-taxonomy.schema.json"),
+      "utf-8",
+    ),
+  ).enum,
+);
+const propertyValue = (subject, name) =>
+  (subject?.properties || []).find((entry) => entry?.name === name)?.value;
+
+const propertyCount = (subject, name) => {
+  const parsed = Number(propertyValue(subject, name));
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+
+/**
+ * Is this internal-model component a real coding-agent definition?
+ *
+ * @param {object} component Internal-model component
+ * @returns {boolean} True for a `cdx:agent:role` component or an
+ *   agent-definition / claude-subagent file
+ */
+export function isDeclaredAgentComponent(component) {
+  if (
+    (component?.properties || []).some(
+      (entry) => entry?.name === AGENT_ROLE_PROPERTY,
+    )
+  ) {
+    return true;
+  }
+  return AGENT_DEFINITION_FILE_KINDS.has(
+    propertyValue(component, "cdx:file:kind"),
+  );
+}
+
+/**
+ * The permissions of an agent: the tool names of `cdx:agent:tools` and the
+ * scopes of `cdx:agent:permissionCapabilities`, each reduced to the name
+ * before any "(", unique and sorted.
+ *
+ * @param {object} component Internal-model agent component
+ * @returns {string[]} Permission names
+ */
+export function declaredAgentPermissions(component) {
+  const names = [
+    ...splitAllowList(propertyValue(component, "cdx:agent:tools")),
+    ...splitAllowList(
+      propertyValue(component, "cdx:agent:permissionCapabilities"),
+    ),
+  ]
+    .map(agentToolName)
+    .filter(Boolean);
+  return [...new Set(names)].sort();
+}
+
+function agentInstances(agent, partyRefId) {
+  const instances = [];
+  const declaresTools =
+    propertyCount(agent, "cdx:agent:toolCount") > 0 ||
+    splitAllowList(propertyValue(agent, "cdx:agent:tools")).length > 0 ||
+    propertyCount(agent, "cdx:agent:mcpServerCount") > 0;
+  if (declaresTools) {
+    instances.push({
+      refId: `behavior-${partyRefId}-invokes-tool`,
+      acknowledgment: ["declared"],
+      behavior: "ai:agent:invokesTool",
+      actors: [partyRefId],
+    });
+  }
+  if (propertyCount(agent, "cdx:agent:permissionAskRuleCount") > 0) {
+    instances.push({
+      refId: `behavior-${partyRefId}-requests-approval`,
+      acknowledgment: ["declared"],
+      behavior: "ai:agent:requestsUserApproval",
+      actors: [partyRefId],
+    });
+  }
+  return instances.filter((instance) =>
+    BEHAVIOR_TAXONOMY.has(instance.behavior),
+  );
+}
+
+function agentParty(agent, partyRefId) {
+  const system = { kind: "agent", ref: agent["bom-ref"] };
+  if (typeof agent.name === "string" && agent.name.length) {
+    system.label = agent.name;
+  }
+  const permissions = declaredAgentPermissions(agent);
+  if (permissions.length) {
+    system.permissions = permissions;
+  }
+  return { refId: partyRefId, roles: [{ role: "agent" }], system };
+}
+
+/**
+ * Collect the 2.0 agent parties and the behavioral blueprint for the
+ * declared agents of an internal-model BOM. Agents without a bom-ref are
+ * skipped (their party could not point at them); parties are unique by
+ * refId.
+ *
+ * @param {object} internalBom The 1.x-shaped internal model
+ * @returns {{parties: object[], blueprint: object|undefined}}
+ */
+export function collectAgentBehaviour(internalBom) {
+  const parties = [];
+  const actors = [];
+  const instances = [];
+  const seen = new Set();
+  for (const agent of internalBom?.components || []) {
+    const bomRef = agent?.["bom-ref"];
+    if (
+      typeof bomRef !== "string" ||
+      !bomRef.length ||
+      !isDeclaredAgentComponent(agent)
+    ) {
+      continue;
+    }
+    const partyRefId = `${AGENT_PARTY_REF_ID_PREFIX}${bomRef}`;
+    if (seen.has(partyRefId)) {
+      continue;
+    }
+    seen.add(partyRefId);
+    parties.push(agentParty(agent, partyRefId));
+    actors.push({ refId: `actor-${partyRefId}`, party: { ref: partyRefId } });
+    instances.push(...agentInstances(agent, partyRefId));
+  }
+  if (!instances.length) {
+    return { parties, blueprint: undefined };
+  }
+  return {
+    parties,
+    blueprint: {
+      refId: AGENT_BLUEPRINT_REF_ID,
+      name: "Declared coding-agent behaviour",
+      modelTypes: ["behavioral"],
+      actors,
+      behaviors: { instances },
+    },
+  };
+}

package/lib/inventory/agentToolNames.js

@@ -0,0 +1,145 @@
+/**
+ * Tool allow lists of coding-agent configurations, reduced to tool names.
+ *
+ * An allow list such as `Read, Bash(git status:*), Bash(curl -u user,secret)`
+ * carries commands, paths and sometimes credentials inside its parentheses.
+ * Only the tool name before any "(" is kept, so nothing an entry scopes its
+ * tool to reaches a BOM. The list is split on the commas outside parentheses,
+ * so the arguments of one entry never become entries of their own.
+ *
+ * A tool name is at most 64 characters of letters, digits and `_ - . : *`
+ * (`Read`, `mcp__github__*`, `fs_write`), optionally in the `@server/tool`
+ * form Kiro uses. A name that looks like a credential (a known token prefix
+ * such as `ghp_` or `AKIA`, or a long run of letters and digits with no
+ * separator) is dropped.
+ */
+
+const NAME_CHARACTERS = new Set(
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._:*-",
+);
+const NAME_SEPARATORS = new Set("._:*-/@");
+const MAX_NAME_LENGTH = 64;
+// Prefixes of GitHub, OpenAI and Anthropic, Slack and AWS access key ids.
+const CREDENTIAL_PREFIXES = Object.freeze([
+  "ghp_",
+  "gho_",
+  "ghu_",
+  "ghs_",
+  "ghr_",
+  "github_pat_",
+  "sk-",
+  "xoxa-",
+  "xoxb-",
+  "xoxp-",
+  "AKIA",
+]);
+// A tool name is a word or words joined by separators; a longer unbroken run
+// of letters and digits that mixes both is treated as a token.
+const MAX_UNSEPARATED_TOKEN_LENGTH = 24;
+
+/**
+ * Split an allow list on the commas outside parentheses. An array is taken
+ * as already split.
+ *
+ * @param {string|string[]|undefined} value Allow list
+ * @returns {string[]} Trimmed, non-empty entries
+ */
+export function splitAllowList(value) {
+  if (Array.isArray(value)) {
+    return value
+      .filter((entry) => typeof entry === "string")
+      .flatMap((entry) => splitAllowList(entry));
+  }
+  const entries = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of `${value ?? ""}`) {
+    if (ch === "(") {
+      depth++;
+    } else if (ch === ")" && depth > 0) {
+      depth--;
+    } else if (ch === "," && depth === 0) {
+      entries.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  entries.push(current);
+  return entries.map((entry) => entry.trim()).filter(Boolean);
+}
+
+function looksLikeCredential(name) {
+  if (CREDENTIAL_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+    return true;
+  }
+  const chars = [...name];
+  return (
+    name.length >= MAX_UNSEPARATED_TOKEN_LENGTH &&
+    !chars.some((ch) => NAME_SEPARATORS.has(ch)) &&
+    chars.some((ch) => ch >= "0" && ch <= "9") &&
+    chars.some((ch) => ch.toLowerCase() !== ch.toUpperCase())
+  );
+}
+
+function isNamePart(part) {
+  return part.length > 0 && [...part].every((ch) => NAME_CHARACTERS.has(ch));
+}
+
+/**
+ * The tool name of one allow-list entry, or undefined when it is not a safe
+ * tool name.
+ *
+ * @param {string} entry Allow-list entry
+ * @returns {string|undefined} Tool name
+ */
+export function agentToolName(entry) {
+  const text = `${entry ?? ""}`;
+  const parenthesis = text.indexOf("(");
+  const name = (parenthesis >= 0 ? text.slice(0, parenthesis) : text).trim();
+  if (!name.length || name.length > MAX_NAME_LENGTH) {
+    return undefined;
+  }
+  const scoped = name.startsWith("@") ? name.slice(1).split("/") : [name];
+  const shapeOk = name.startsWith("@")
+    ? scoped.length === 2 && scoped.every(isNamePart)
+    : isNamePart(name);
+  if (!shapeOk || looksLikeCredential(name)) {
+    return undefined;
+  }
+  return name;
+}
+
+/**
+ * The unique, sorted tool names of an allow list.
+ *
+ * @param {string|string[]|undefined} value Allow list
+ * @returns {string[]} Tool names
+ */
+export function agentToolNames(value) {
+  return [
+    ...new Set(splitAllowList(value).map(agentToolName).filter(Boolean)),
+  ].sort();
+}
+
+/**
+ * An allow list as cdxgen records it in `cdx:agent:tools` and
+ * `cdx:agent:disallowedTools`: each entry reduced to its tool name, written
+ * `Name(...)` when the entry scoped the tool with arguments, so a scoped
+ * `Bash(git status:*)` stays distinguishable from an unrestricted `Bash`
+ * without copying the scope. Unique, in the order the config lists them,
+ * comma separated.
+ *
+ * @param {string|string[]|undefined} value Allow list
+ * @returns {string|undefined} Summary, or undefined when nothing is left
+ */
+export function summarizeAgentToolList(value) {
+  const summary = new Set();
+  for (const entry of splitAllowList(value)) {
+    const name = agentToolName(entry);
+    if (name) {
+      summary.add(entry.includes("(") ? `${name}(...)` : name);
+    }
+  }
+  return summary.size ? [...summary].join(",") : undefined;
+}

package/lib/inventory/aiCollector.js

@@ -29,6 +29,7 @@ import {
   repositoryUrlForHuggingFaceAssetType,
   toHuggingFaceAssetUrl,
   toHuggingFacePurl,
+  toHuggingFaceSupplier,
 } from "../parsers/huggingfaceUtils.js";
 import { parseOllamaModelfile } from "../parsers/ollama.js";
 import { readOnnxHeader } from "../parsers/onnx.js";
@@ -37,6 +38,12 @@ import {
   detectAiModelVariants,
   normalizeDetectedVariants,
 } from "./aiModelVariants.js";
+import {
+  modelCreatorEntity,
+  modelCreatorFromOrganization,
+  resolveModelCreator,
+  splitModelReference,
+} from "./aiProviders.js";
 import { getLicenses } from "./spdx.js";
 
 // -----------------------------------------------------------------------------
@@ -98,7 +105,8 @@ const IGNORE_SOURCE_FILE_PATTERN =
 const HOST_PROVIDER_PATTERNS = [
   ["openai", /(?:^|\.)openai\.com$/iu],
   ["anthropic", /(?:^|\.)anthropic\.com$/iu],
-  ["google", /(?:^|\.)googleapis\.com$/iu],
+  // Only the Gemini API host. Other googleapis.com hosts serve Cloud Storage,
+  // Vertex AI (matched below) and unrelated Google APIs.
   ["google", /(?:^|\.)generativelanguage\.googleapis\.com$/iu],
   ["azure-openai", /(?:^|\.)openai\.azure\.com$/iu],
   ["huggingface", /(?:^|\.)huggingface\.co$/iu],
@@ -110,7 +118,9 @@ const HOST_PROVIDER_PATTERNS = [
   ["together", /(?:^|\.)together\.xyz$/iu],
   ["replicate", /(?:^|\.)replicate\.com$/iu],
   ["perplexity", /(?:^|\.)perplexity\.ai$/iu],
-  ["vertex-ai", /(?:^|\.)aiplatform\.googleapis\.com$/iu],
+  // Regional Vertex AI endpoints join the region with a hyphen, as in
+  // us-central1-aiplatform.googleapis.com.
+  ["vertex-ai", /(?:^|[.-])aiplatform\.googleapis\.com$/iu],
   ["xai", /(?:^|\.)x\.ai$/iu],
   [
     "aws-bedrock",
@@ -1326,9 +1336,62 @@ const createAiFileComponent = (
   return componentsByKey.get(key);
 };
 
+// Longest producer name a model file may declare about itself.
+const MAX_DECLARED_PRODUCER_LENGTH = 128;
+
+/**
+ * Trim and bound a producer name a model file declares about itself, such as
+ * the GGUF general.organization field. The value is file-controlled free text.
+ *
+ * @param {unknown} value Declared producer
+ * @returns {string|undefined} Usable producer name
+ */
+const declaredProducerName = (value) => {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const name = value.trim();
+  if (!name || name.length > MAX_DECLARED_PRODUCER_LENGTH) {
+    return undefined;
+  }
+  return name;
+};
+
+/**
+ * Build the manufacturer of a model, the organisation that created it.
+ *
+ * A producer the model file declares about itself wins, written with the
+ * creator's full name when it is a known creator and as declared otherwise.
+ * A Hub repository credits its namespace only when the namespace is the
+ * creator's own organisation (meta-llama, mistralai, Qwen), because
+ * re-packagers such as TheBloke, unsloth or mlx-community publish models
+ * other organisations made. A model that source code calls by name uses the
+ * creator id the caller resolved.
+ *
+ * @param {{ hubNamespace?: string, modelCreator?: string, producer?: unknown }} sources
+ *   Creator evidence for the model
+ * @returns {{ name: string }|undefined} Manufacturer entity
+ */
+const modelManufacturer = ({ hubNamespace, modelCreator, producer }) => {
+  const declared = declaredProducerName(producer);
+  if (declared) {
+    return (
+      modelCreatorEntity(modelCreatorFromOrganization(declared)) || {
+        name: declared,
+      }
+    );
+  }
+  if (hubNamespace) {
+    return modelCreatorEntity(modelCreatorFromOrganization(hubNamespace));
+  }
+  return modelCreatorEntity(modelCreator);
+};
+
 const normalizeComponentIdentity = ({
   assetType,
+  modelCreator,
   modelId,
+  producer,
   provider,
   version,
 }) => {
@@ -1343,7 +1406,14 @@ const normalizeComponentIdentity = ({
       : normalizedAssetType === "space"
         ? `spaces/${normalizedModelId.replace(/^spaces\//u, "")}`
         : normalizedModelId;
-  const repoId = normalizeHuggingFaceReference(typedModelId);
+  // A litellm route such as groq/llama3-8b or a Google resource name such as
+  // models/gemini-1.5-flash has the shape of a Hub repository id but is not
+  // one, so its first segment is never taken as a Hub namespace.
+  const repoId =
+    normalizedAssetType === "model" &&
+    splitModelReference(normalizedModelId).nonHub
+      ? undefined
+      : normalizeHuggingFaceReference(typedModelId);
   if (
     repoId?.assetType === normalizedAssetType &&
     repoId?.repoId?.includes("/")
@@ -1354,11 +1424,24 @@ const normalizeComponentIdentity = ({
       repoId.version || version,
       repositoryUrlForHuggingFaceAssetType(normalizedAssetType),
     );
+    // The Hub namespace is the account that published the repository, so it
+    // is the supplier. Its Hub page is the supplier url only when the model
+    // came from the Hub; a routed id such as meta-llama/Llama-3-70b on
+    // together keeps the name.
+    const hubSupplier = toHuggingFaceSupplier(group);
     return {
       bomRef: purl,
       group,
+      manufacturer:
+        normalizedAssetType === "model"
+          ? modelManufacturer({ hubNamespace: group, producer })
+          : undefined,
       name,
       purl,
+      supplier:
+        hubSupplier && normalizedProvider.toLowerCase() !== "huggingface"
+          ? { name: hubSupplier.name }
+          : hubSupplier,
     };
   }
   return {
@@ -1368,6 +1451,12 @@ const normalizeComponentIdentity = ({
       normalizedModelId,
     ),
     group: normalizedProvider,
+    // Hosting, routing and local providers stay in group and
+    // cdx:ai:provider; only the creator is the manufacturer.
+    manufacturer:
+      normalizedAssetType === "model"
+        ? modelManufacturer({ modelCreator, producer })
+        : undefined,
     name: normalizedModelId,
   };
 };
@@ -1390,6 +1479,11 @@ const ensureModelComponent = (componentsByKey, key, seed) => {
       description: seed.description,
       version: seed.version,
       licenses: seed.licenses,
+      // The organisation that created the model is the manufacturer. The
+      // Hugging Face namespace that published the repository is the
+      // supplier.
+      manufacturer: identity.manufacturer,
+      supplier: identity.supplier,
       externalReferences: seed.externalReferences || [],
       evidence: { occurrences: [] },
       modelCard: seed.modelCard
@@ -1691,6 +1785,25 @@ const scanUrlMatches = (
   }
 };
 
+// A plausible model id: 2-160 characters with no whitespace, starting with an
+// alphanumeric (or the `@` of a scoped id such as Cloudflare's `@cf/...`) and
+// otherwise limited to name, scope, version, and registry punctuation.
+// Markdown prose around an inline `` `model:` `` label fails these checks, so
+// documentation such as "editing the `model:` field. Run `kiro-cli chat
+// --list-models`" does not become a model.
+const MODEL_ID_CHARS_PATTERN = /^@?[A-Za-z0-9][A-Za-z0-9._:/@+-]*$/u;
+const MODEL_ID_MIN_LENGTH = 2;
+const MODEL_ID_MAX_LENGTH = 160;
+
+const isPlausibleModelId = (value) => {
+  const normalized = String(value || "").trim();
+  return (
+    normalized.length >= MODEL_ID_MIN_LENGTH &&
+    normalized.length <= MODEL_ID_MAX_LENGTH &&
+    MODEL_ID_CHARS_PATTERN.test(normalized)
+  );
+};
+
 const extractModelAssignments = (raw) => {
   const values = [];
   const patterns = [
@@ -1708,9 +1821,10 @@ const extractModelAssignments = (raw) => {
   }
   return values.filter((entry) => {
     const normalized = String(entry.value || "").trim();
-    return (
-      normalized && !normalized.startsWith("http") && normalized !== "auto"
-    );
+    if (!normalized || normalized.startsWith("http") || normalized === "auto") {
+      return false;
+    }
+    return isPlausibleModelId(normalized);
   });
 };
 
@@ -1732,6 +1846,15 @@ const extractHuggingFaceReferences = (raw) => {
     }
   }
   return refs
+    .filter(
+      (entry) =>
+        // URL-derived references are already anchored to a real host, while
+        // quoted `repo_id`/`model` captures suffer the same backtick-as-quote
+        // ambiguity as model assignments, so they must look like an id too.
+        entry.sourceUrl ||
+        (isPlausibleModelId(entry.value) &&
+          !splitModelReference(entry.value).nonHub),
+    )
     .map((entry) => {
       const reference = normalizeHuggingFaceReference(entry.value);
       return {
@@ -1770,7 +1893,16 @@ const createModelComponent = (componentsByKey, seed, occurrenceLocation) => {
     ? seed.assetType
     : "model";
   const key = `${normalizedAssetType}:${seed.provider || "ai"}:${seed.modelId}`;
+  const isKnownComponent = componentsByKey.has(key);
   const component = ensureModelComponent(componentsByKey, key, seed);
+  // The same model can be seen first in a file that names no creator and
+  // later in one that does, so a later seed fills a missing manufacturer.
+  if (isKnownComponent && !component.manufacturer) {
+    const { manufacturer } = normalizeComponentIdentity(seed);
+    if (manufacturer) {
+      component.manufacturer = manufacturer;
+    }
+  }
   syncComponentProperties(component, {
     artifactFormat: seed.artifactFormat,
     confidence: seed.confidence,
@@ -1900,14 +2032,25 @@ const collectTextAiInventory = (discoveryPath, options = {}, config = {}) => {
     }
     for (const match of extractModelAssignments(raw)) {
       const modelId = String(match.value || "").trim();
+      // Only a provider the file declares through an SDK import or AI host
+      // may agree with the creator. The fallback guessed from the model name
+      // stays in group and cdx:ai:provider.
+      const declaredProvider = Array.from(fileSignals.providers)[0];
       const provider =
-        Array.from(fileSignals.providers)[0] || providerFromModelName(modelId);
+        declaredProvider ||
+        splitModelReference(modelId).routeProvider ||
+        providerFromModelName(modelId);
       const component = createModelComponent(
         componentsByKey,
         {
           assetType: "model",
           confidence: "medium",
           kind: "model",
+          modelCreator: resolveModelCreator(modelId, {
+            fileProviders: fileSignals.providers,
+            provider: declaredProvider,
+            runtimes: fileSignals.runtimes,
+          }),
           modelFamily: modelFamilyFromName(modelId),
           modelId,
           provider,
@@ -2102,6 +2245,9 @@ export function collectJsAiInventory(discoveryPath, options = {}) {
           ggufModelIdFromFilename(parsedFileName, filePath),
         parameterCount: metadata["general.parameter_count"],
         pedigree: createGgufPedigree(metadata),
+        // general.organization is the creator the file declares, so it is
+        // the manufacturer even when it is not a known creator.
+        producer: metadata["general.organization"],
         provider: metadata["general.organization"] || "local",
         quantization,
         reviewNeeded: true,