JGC-473 - Add AI-agent help text to security commands

cli/docs/auditspecific/help.go

@@ -6,26 +6,67 @@ import "fmt"
 
 const descFormat = "Execute an audit %s command, using the configured Xray details."
 
+const aiDescFormat = `Run a tech-restricted audit limited to %s dependencies. Deprecated: prefer ` + "`jf audit --%s`" + ` over this dedicated subcommand. Use only when integrating with legacy scripts that still call the per-technology audit command.
+
+When to use:
+- Maintaining older CI scripts that have not yet migrated to the unified jf audit interface.
+
+Prerequisites:
+- Configured JFrog Platform server (jf c add) with Xray entitlement.
+- The %s toolchain installed and reachable on PATH.
+
+Common patterns:
+  $ jf audit --%s
+
+Gotchas:
+- This command emits a deprecation warning at runtime and will be removed in the next CLI major version.
+
+Related: jf audit`
+
 func GetGoDescription() string {
 	return fmt.Sprintf(descFormat, "Go")
 }
 
+func GetGoAIDescription() string {
+	return fmt.Sprintf(aiDescFormat, "Go", "go", "Go", "go")
+}
+
 func GetGradleDescription() string {
 	return fmt.Sprintf(descFormat, "Gradle")
 }
 
+func GetGradleAIDescription() string {
+	return fmt.Sprintf(aiDescFormat, "Gradle", "gradle", "Gradle", "gradle")
+}
+
 func GetMvnDescription() string {
 	return fmt.Sprintf(descFormat, "Maven")
 }
 
+func GetMvnAIDescription() string {
+	return fmt.Sprintf(aiDescFormat, "Maven", "mvn", "Maven", "mvn")
+}
+
 func GetNpmDescription() string {
 	return fmt.Sprintf(descFormat, "Npm")
 }
 
+func GetNpmAIDescription() string {
+	return fmt.Sprintf(aiDescFormat, "npm", "npm", "Node.js/npm", "npm")
+}
+
 func GetPipDescription() string {
 	return fmt.Sprintf(descFormat, "Pip")
 }
 
+func GetPipAIDescription() string {
+	return fmt.Sprintf(aiDescFormat, "Pip (Python)", "pip", "Python with pip", "pip")
+}
+
 func GetPipenvDescription() string {
 	return fmt.Sprintf(descFormat, "Pipenv")
 }
+
+func GetPipenvAIDescription() string {
+	return fmt.Sprintf(aiDescFormat, "Pipenv (Python)", "pipenv", "Python with Pipenv", "pipenv")
+}

cli/docs/enrich/help.go

@@ -8,6 +8,31 @@ func GetDescription() string {
 	return "Enrich sbom format JSON located on the local file-system with Xray."
 }
 
+func GetAIDescription() string {
+	return `Send an existing CycloneDX SBOM JSON file to Xray for enrichment with vulnerability and license metadata. Use when an agent has produced an SBOM from another tool (Syft, CDXgen, Maven, etc.) and wants Xray's intelligence layered on top without rerunning a full dependency resolution.
+
+When to use:
+- Annotate a third-party-generated CycloneDX SBOM with Xray vulnerability and license data.
+- Add Xray context to SBOMs produced earlier in a CI pipeline.
+- Bridge external SBOM tooling with the JFrog Platform.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add) with Xray entitlement.
+- An input CycloneDX SBOM JSON file on the local filesystem.
+- The SBOM must contain components Xray can resolve (purl identifiers).
+
+Common patterns:
+  $ jf sbom-enrich path/to/sbom.cdx.json
+  $ jf se path/to/sbom.cdx.json --threads=4
+
+Gotchas:
+- Input must be CycloneDX JSON; SPDX or other formats are not accepted.
+- Components without a resolvable purl will not be enriched.
+- The command requires the file-path argument; no spec-based input is supported.
+
+Related: jf audit, jf scan, jf upload-cdx`
+}
+
 func GetArguments() []components.Argument {
 	return []components.Argument{{Name: "File path", Description: `Specifies the local file system path of the JSON to be scanned.`}}
 }

cli/docs/git/audit/help.go

@@ -3,3 +3,30 @@ package audit
 func GetDescription() string {
 	return "Audit your local git repository project for security issues."
 }
+
+func GetAIDescription() string {
+	return `Audit a local Git repository for security issues by combining SCA dependency scanning with JAS scans (SAST, Secrets, IaC, Applicability) and correlating findings to Git/VCS metadata (remote URL, branch, commit) so results surface in the Platform under the right Git context. Use when an agent wants jf audit results tagged with repository identity for cross-PR/cross-branch tracking.
+
+When to use:
+- Scan a working tree the same way a PR/CI bot would, with Git context attached.
+- Aggregate audit findings per repository in the JFrog Platform UI.
+- Run a snippet-aware SAST scan on changed files.
+
+Prerequisites:
+- Configured JFrog Platform server (jf c add) with Xray (and JAS for advanced scans).
+- The current working directory must be inside a Git repository (with a remote and at least one commit).
+- analyzerManager binary (auto-installed) for JAS scans.
+
+Common patterns:
+  $ jf git audit
+  $ jf git audit --format=sarif --output-dir=./results
+  $ jf git audit --watches=my-watch --fail=true
+  $ jf git audit --sast --secrets --threads=4
+
+Gotchas:
+- Requires a Git repo with valid remote metadata; otherwise context resolution fails.
+- The command is currently hidden from top-level help.
+- Without --watches or --project, only general vulnerabilities are reported.
+
+Related: jf audit, jf scan, jf git count-contributors`
+}

cli/docs/git/contributors/help.go

@@ -3,3 +3,31 @@ package contributors
 func GetContContributorsDescription() string {
 	return "List all GIT providers' contributing developers."
 }
+
+func GetContContributorsAIDescription() string {
+	return `Count unique contributing developers across one or more Git repositories on GitHub, GitLab, or Bitbucket Server over a configurable time window. Use when an agent needs developer-count data for JFrog licensing/seat reporting or compliance audits.
+
+When to use:
+- Compute the developer-seat count for a JFrog license review.
+- Produce a per-repo or per-organization contributor report for compliance.
+- Aggregate counts across many repositories from an input file.
+
+Prerequisites:
+- A personal access token for the SCM provider with read access to the target repos.
+- Either --input-file pointing to a repo list JSON, or the full set of mandatory flags: --scm-type, --token (or env var), --owner, --scm-api-url.
+- Supported --scm-type values: github, gitlab, bitbucketServer.
+- Optional env vars for tokens: JFROG_CLI_GITHUB_TOKEN, JFROG_CLI_GITLAB_TOKEN, JFROG_CLI_BITBUCKET_TOKEN, or the generic JFROG_CLI_GIT_TOKEN.
+
+Common patterns:
+  $ jf git count-contributors --scm-type=github --token=$GITHUB_TOKEN --owner=my-org --scm-api-url=https://api.github.com
+  $ jf git cc --scm-type=gitlab --owner=my-group --scm-api-url=https://gitlab.com/api/v4 --repo-name="repo-a;repo-b"
+  $ jf git count-contributors --input-file=repos.json --months=12 --detailed-summary
+
+Gotchas:
+- --months must be a positive integer; defaults to a built-in window if omitted.
+- When --input-file is used, the other mandatory flags are ignored.
+- --repo-name is a semicolon-separated list, not comma-separated.
+- The command is currently hidden from top-level help.
+
+Related: jf git audit`
+}

cli/docs/maliciousscan/help.go

@@ -8,6 +8,31 @@ func GetDescription() string {
 	return "[Beta] Scan malicious models (pickle files, etc.) located in the working directory."
 }
 
+func GetAIDescription() string {
+	return `[Beta] Scan the working directory for malicious ML model artifacts (Python pickle files, serialized models) using the JAS analyzerManager. Use when an agent ingests untrusted models from public registries (HuggingFace, model zoos) and needs to detect embedded code-execution payloads before loading them.
+
+When to use:
+- Vet downloaded .pkl, .pt, .pth, .joblib, .h5, .pb model files before loading into a Python runtime.
+- Add a malicious-model gate to ML supply-chain pipelines.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add) with JFrog Advanced Security entitlement.
+- The analyzerManager binary (auto-installed); pass --analyzer-manager-path to override.
+- Run from the directory containing the model files, or pass --working-dirs.
+
+Common patterns:
+  $ jf malicious-scan
+  $ jf ms --working-dirs=./models --format=sarif
+  $ jf malicious-scan --min-severity=High --project=my-project
+
+Gotchas:
+- Beta surface; flags and output schema may change.
+- Only known malicious-model patterns are detected; this is not a general SCA or SAST scan.
+- Without --working-dirs, only the current directory is scanned.
+
+Related: jf audit, jf scan`
+}
+
 func GetArguments() []components.Argument {
 	return []components.Argument{}
 }

cli/docs/mcp/help.go

@@ -8,6 +8,30 @@ func GetDescription() string {
 	return "Runs a local source code analysis as a local MCP server, allowing access to tools which reflect source code analysis"
 }
 
+func GetAIDescription() string {
+	return `Launch a local Model Context Protocol (MCP) server that exposes JFrog source-code analysis (SCA + JAS scans) as MCP tools over stdio. Use when an AI coding agent needs interactive, tool-callable access to scan results on the developer's machine; the agent (Claude Code, Cursor, etc.) starts this process and communicates via JSON-RPC on stdin/stdout.
+
+When to use:
+- Wire JFrog security scanning into an MCP-aware AI client as a local tool provider.
+- Provide an agent with on-demand vulnerability, secret, SAST, and IaC scans of the user's codebase.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add) with Xray and JFrog Advanced Security entitlements.
+- analyzerManager binary available (auto-installed on first run).
+- The host process must be an MCP client capable of speaking JSON-RPC over the spawned process's stdio.
+
+Common patterns:
+  $ jf source-mcp /path/to/project
+  $ jf source-mcp ./
+
+Gotchas:
+- This command is intended to be spawned by an MCP client, not run interactively in a terminal; stdout is reserved for JSON-RPC frames.
+- Logs go to stderr; do not pipe stderr into the MCP transport.
+- The command is currently hidden from top-level help while the integration matures.
+
+Related: jf audit, jf scan, jf sast-server`
+}
+
 func GetArguments() []components.Argument {
 	return []components.Argument{{Name: "Source path", Description: `Specifies the local file system path of source code to analyze.`}}
 }

cli/docs/sastserver/help.go

@@ -3,3 +3,27 @@ package sast_server
 func GetDescription() string {
 	return "Runs a local source code analysis as a local SAST server, allowing access to tools which reflect source code analysis"
 }
+
+func GetAIDescription() string {
+	return `Start a local HTTP server that exposes JFrog SAST source-code analysis endpoints, enabling other tools (IDE plugins, AI agents, custom integrations) to request scans over HTTP instead of spawning the CLI per call. Use when a long-running client needs to invoke SAST repeatedly against changing files.
+
+When to use:
+- Back an IDE extension or AI agent with a persistent local SAST endpoint.
+- Avoid analyzerManager startup overhead by serving multiple scan requests from one process.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add) with JFrog Advanced Security entitlement.
+- analyzerManager binary available (auto-installed on first run).
+- A free TCP port for the server to bind to (passed via --port).
+
+Common patterns:
+  $ jf sast-server --port=8080
+  $ jf sast-server --port=9000
+
+Gotchas:
+- --port is mandatory; the command exits with an error if it is omitted.
+- The server binds only to localhost; it is not intended for remote access.
+- The command is currently hidden from top-level help.
+
+Related: jf audit, jf source-mcp`
+}

cli/docs/scan/audit/help.go

@@ -3,3 +3,33 @@ package audit
 func GetDescription() string {
 	return "Scan your source code on demand to detect CVEs, license issues, misconfigurations, secrets, and other risks, with results shown in the terminal and in the JFrog Platform."
 }
+
+func GetAIDescription() string {
+	return `Run a local source-code security audit against the JFrog Platform (Xray + JAS). Combines Software Composition Analysis (SCA) on the project's dependency graph with optional JFrog Advanced Security scans: Applicability/Contextual Analysis, IAC, Secrets Detection, SAST, and Malicious Code. Use this when an agent needs to assess a checked-out project before committing, opening a PR, or releasing.
+
+When to use:
+- Inspect a local repo for CVEs, license violations, IaC misconfigurations, leaked secrets, or SAST findings.
+- Gate a build by failing on policy violations from configured watches or a project key.
+- Produce SARIF or SBOM (CycloneDX) output for IDE/CI consumption.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add) with Xray entitlement.
+- For JAS scans (SAST/IAC/Secrets/Applicability): a JFrog Advanced Security subscription.
+- The auto-installed analyzerManager binary; pass --analyzer-manager-path to override or --skip-auto-install to use a pre-staged copy.
+- Package-manager tooling (e.g., mvn, gradle, npm, pip, go) must be on PATH for tech-specific dependency resolution.
+
+Common patterns:
+  $ jf audit
+  $ jf audit --format=sarif --output-dir=./scan-results
+  $ jf audit --watches=my-watch1,my-watch2 --fail=true
+  $ jf audit --project=my-project --vuln --licenses
+  $ jf audit --sca --sast --secrets --working-dirs=services/api,services/web
+
+Gotchas:
+- Without --watches, --project, or --repo-path, no policy violations are evaluated; the command only reports raw vulnerabilities.
+- --fail defaults to true: a CI run will exit non-zero on findings unless explicitly set to false.
+- Technology flags (--mvn, --gradle, --npm, --go, --pip, --pipenv, --nuget, --yarn) restrict the scan; otherwise auto-detection runs every detected stack.
+- --add-sast-rules requires --sast to be active.
+
+Related: jf scan, jf build-scan, jf curation-audit, jf sbom-enrich`
+}

cli/docs/scan/buildscan/help.go

@@ -6,6 +6,34 @@ func GetDescription() string {
 	return "Scan a published build-info with Xray."
 }
 
+func GetAIDescription() string {
+	return `Trigger an Xray scan against an already-published build-info record in Artifactory. Use when an agent has run jf rt build-publish for a CI build and wants to fetch the Xray verdict (vulnerabilities and violations) for that exact build/number pair before promoting or distributing it.
+
+When to use:
+- Gate promotion/distribution on a build's Xray scan results.
+- Wait for Xray to finish scanning a freshly published build and surface findings.
+- Re-scan an existing build after policy or DB updates.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add) with Xray entitlement.
+- The build-info must already be published to Artifactory (jf rt build-publish).
+- For violations: the build must be associated with a project key or matched by Xray watches.
+
+Common patterns:
+  $ jf build-scan my-build 42
+  $ jf bs my-build 42 --fail=true --format=sarif
+  $ jf build-scan my-build 42 --project=my-project --vuln --violations
+  $ jf build-scan my-build 42 --rescan=true --extended-table
+
+Gotchas:
+- If build name/number are omitted, values from the build configuration env or jfrog-cli build context are used.
+- --fail defaults to true; set --fail=false to inspect results without exiting non-zero.
+- Xray may need time to index the build; --trigger-scan-retries controls how long the CLI waits.
+- Without project/watches, no violations are produced even if --violations is set.
+
+Related: jf audit, jf scan, jf rt build-publish`
+}
+
 func GetArguments() []components.Argument {
 	return []components.Argument{
 		{

cli/docs/scan/curation/help.go

@@ -3,3 +3,32 @@ package curation
 func GetDescription() string {
 	return "Audit your project dependencies for their curation status."
 }
+
+func GetAIDescription() string {
+	return `Inspect the project's package-manager dependencies against the JFrog Curation service and report which packages were blocked by curation policy along with the matching policies. Use when an agent suspects a package install failure was due to curation, or wants a preemptive curation report.
+
+When to use:
+- Diagnose 403/forbidden errors during npm/pip/maven/gradle/nuget/go install steps in a curation-enabled remote.
+- Produce a curation-status report (blocked packages and policies) for the current project.
+- Run automatically after a failed install via the JFROG_CLI_SKIP_CURATION_AFTER_FAILURE workflow.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add) with JFrog Curation entitlement.
+- Project must use a supported package manager (npm, yarn, pip, maven, gradle, nuget, go) resolved through a curation-configured remote.
+- The package manager and its lockfile must be present in the working directory.
+
+Common patterns:
+  $ jf curation-audit
+  $ jf ca --working-dirs=services/api,services/web
+  $ jf curation-audit --format=json --threads=4
+  $ jf curation-audit --requirements-file=requirements-dev.txt
+  $ jf curation-audit --docker-image=my-image:tag
+
+Gotchas:
+- The user/token must be entitled for Curation; otherwise the command exits with an entitlement notice.
+- Requires the project's package manager binary on PATH (npm, mvn, etc.).
+- Run from the project root or pass --working-dirs.
+- For Maven multi-module: --use-wrapper if mvnw is used.
+
+Related: jf audit, jf rt npm-install, jf rt mvn`
+}

cli/docs/scan/dockerscan/help.go

@@ -6,6 +6,33 @@ func GetDescription() string {
 	return "Scan local docker image using the docker client and Xray."
 }
 
+func GetAIDescription() string {
+	return `Scan a local Docker image (resolved via the local docker daemon) against Xray and JAS for vulnerabilities, license issues, secrets, and applicability. Invoked as the sub-command of jf docker. Use when an agent has built or pulled an image and wants Xray's verdict on it before pushing or running.
+
+When to use:
+- Inspect a freshly built image (e.g., from a Dockerfile) before pushing to a registry.
+- Scan a third-party image pulled to the local daemon.
+- Generate SARIF or CycloneDX for CI gating of container builds.
+
+Prerequisites:
+- Configured JFrog Platform server (jf c add) with Xray entitlement; JAS scans require Advanced Security.
+- A running Docker daemon and the image present locally (docker images shows it).
+- For applicability/JAS layers: the analyzerManager binary (auto-installed).
+
+Common patterns:
+  $ jf docker scan my-image:latest
+  $ jf docker scan my-image:1.2.3 --format=sarif --fail=true
+  $ jf docker scan my-registry/my-image:tag --watches=prod-watch --vuln
+  $ jf docker scan my-image:tag --bypass-archive-limits --threads=4
+
+Gotchas:
+- The image must already be loaded into the local Docker daemon; this command does not pull from a registry.
+- --bypass-archive-limits may be required for large layers.
+- Without --watches or --project, only general vulnerabilities are reported (no violations).
+
+Related: jf scan, jf audit, jf build-scan`
+}
+
 func GetArguments() []components.Argument {
 	return []components.Argument{
 		{