feat: Add support for AI discovery (#685)

* feat: Add support for AI usage discovery

* fix: Validate coding agent discovery

* docs: Update README

* fix: Add missing test fixture

* fix: Remove stale spec

* refactor: Re-use MCP config structs

* refactor: Use scopes for discovery

* refactor: Use apps instead of hosts

* refactor: Set context as top level dependency

* fix: Code review fixes

* refactor: Protect internal concerns

* fix: Hoist regex.MustCompile

* fix: Code review fixes

Author: abhisek

.gitignore

@@ -28,4 +28,5 @@ dist/
 **/.DS_Store
 
 # Auto-generated context files
-CLAUDE.md
+/CLAUDE.md
+.devcontainer

README.md

@@ -43,10 +43,11 @@
 
 Traditional SCA tools drown you in CVE noise. **vet** takes a different approach:
 
-- **Catch malware before it ships** — Zero-day detection through static and dynamic behavioral analysis, not just advisory lookups
-- **Cut through vulnerability noise** — Analyzes your actual code usage to surface only the risks that matter
-- **Secure AI-generated code** — [MCP server](./docs/mcp.md) integration protects against [slopsquatting](https://en.wikipedia.org/wiki/Slopsquatting) in tools like Cursor, VS Code, and Claude Code
-- **Enforce policy as code** — Express security, license, and quality requirements as [CEL](https://cel.dev/) expressions that gate your CI/CD pipeline
+- **Shadow AI discovery** — Discover AI tool usage signals across various tools and configurations
+- **Catch malware before it ships** — Zero-day detection through static and dynamic behavioral analysis (requires SafeDep Cloud access)
+- **Cut through vulnerability noise** — Analyzes actual code usage to surface only the risks that matter
+- **Enforce policy as code** — Express security, license, and quality requirements as [CEL](https://cel.dev/) expressions
+- **CI/CD integration** — Zero-config security guardrails in CI/CD
 
 Free for open source. Hosted SaaS available at [SafeDep](https://safedep.io).
 
@@ -278,8 +279,9 @@ vet version
 
 **Learn more in our comprehensive documentation:**
 
-- **[MCP Server](./docs/mcp.md)** - Run vet as an MCP server for AI-assisted code analysis
+- **[AI Usage Discovery](./docs/ai-discovery.md)** - Discover AI tool usage signals across various tools and configurations
 - **[AI Agent Mode](./docs/agent.md)** - Run vet as an AI agent
+- **[MCP Server](./docs/mcp.md)** - Run vet as an MCP server for AI-assisted code analysis
 - **[Reporting](./docs/reporting.md)** - SARIF, JSON, CSV, HTML, Markdown formats
 - **[SBOM Support](https://docs.safedep.io/vet/guides/cyclonedx-sbom)** - CycloneDX, SPDX import/export
 - **[Query Mode](https://docs.safedep.io/cloud/quickstart#query-your-data)** - Scan once, analyze multiple times

cmd/ai/discover.go

@@ -0,0 +1,205 @@
+package ai
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/jedib0t/go-pretty/v6/table"
+	"github.com/spf13/cobra"
+
+	"github.com/safedep/vet/pkg/aitool"
+	"github.com/safedep/vet/pkg/common/logger"
+)
+
+var (
+	discoverScopes     []string
+	discoverProjectDir string
+	discoverReportJSON string
+	discoverSilent     bool
+)
+
+func newDiscoverCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "discover",
+		Short: "Discover AI tools usage, MCP servers, and coding agents",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			redirectLogOutput(cmd)
+			return runDiscover(cmd.Context())
+		},
+	}
+
+	cmd.Flags().StringArrayVar(&discoverScopes, "scope", nil, "Limit to specific scopes (system, project); repeatable, empty for all")
+	cmd.Flags().StringVarP(&discoverProjectDir, "project-dir", "D", "", "Project root for project-level discovery (default: cwd)")
+	cmd.Flags().StringVar(&discoverReportJSON, "report-json", "", "Write JSON inventory to file")
+	cmd.Flags().BoolVarP(&discoverSilent, "silent", "s", false, "Suppress default summary output")
+
+	return cmd
+}
+
+func runDiscover(ctx context.Context) error {
+	projectDir := discoverProjectDir
+	if projectDir == "" {
+		var err error
+		projectDir, err = os.Getwd()
+		if err != nil {
+			return fmt.Errorf("failed to get working directory: %w", err)
+		}
+	}
+
+	scope, err := buildDiscoveryScope(discoverScopes)
+	if err != nil {
+		return err
+	}
+
+	config := aitool.DiscoveryConfig{
+		ProjectDir: projectDir,
+		Scope:      scope,
+	}
+
+	registry := aitool.DefaultRegistry()
+	inventory := aitool.NewAIToolInventory()
+
+	err = registry.Discover(ctx, config, func(tool *aitool.AITool) error {
+		inventory.Add(tool)
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+
+	if !discoverSilent {
+		printSummaryTable(inventory)
+	}
+
+	if discoverReportJSON != "" {
+		if err := writeJSONInventory(inventory, discoverReportJSON); err != nil {
+			return fmt.Errorf("failed to write JSON report: %w", err)
+		}
+	}
+
+	return nil
+}
+
+func printSummaryTable(inventory *aitool.AIToolInventory) {
+	apps := inventory.GroupByApp()
+
+	fmt.Fprintf(os.Stderr, "\nDiscovered %d AI tool usage(s) across %d app(s)\n\n",
+		len(inventory.Tools), len(apps))
+
+	if len(inventory.Tools) == 0 {
+		return
+	}
+
+	tbl := table.NewWriter()
+	tbl.SetOutputMirror(os.Stderr)
+	tbl.SetStyle(table.StyleLight)
+
+	tbl.AppendHeader(table.Row{"TYPE", "NAME", "APP", "SCOPE", "DETAIL"})
+
+	for _, tool := range inventory.Tools {
+		detail := toolDetail(tool)
+		tbl.AppendRow(table.Row{
+			string(tool.Type),
+			tool.Name,
+			tool.App,
+			string(tool.Scope),
+			detail,
+		})
+	}
+
+	tbl.Render()
+	fmt.Fprintln(os.Stderr)
+}
+
+func toolDetail(tool *aitool.AITool) string {
+	switch tool.Type {
+	case aitool.AIToolTypeMCPServer:
+		if tool.MCPServer != nil {
+			if tool.MCPServer.Command != "" {
+				detail := string(tool.MCPServer.Transport) + ": " + tool.MCPServer.Command
+				if len(tool.MCPServer.Args) > 0 {
+					for _, arg := range tool.MCPServer.Args {
+						detail += " " + arg
+					}
+				}
+				return detail
+			}
+			if tool.MCPServer.URL != "" {
+				return string(tool.MCPServer.Transport) + ": " + tool.MCPServer.URL
+			}
+		}
+		return tool.ConfigPath
+	case aitool.AIToolTypeCLITool:
+		version := tool.GetMetaString("binary.version")
+		path := tool.GetMetaString("binary.path")
+		if version != "" {
+			return path + " v" + version
+		}
+		return path
+	case aitool.AIToolTypeAIExtension:
+		id := tool.GetMetaString("extension.id")
+		version := tool.GetMetaString("extension.version")
+		ide := tool.GetMetaString("extension.ide")
+		detail := id
+		if version != "" {
+			detail += " v" + version
+		}
+		if ide != "" {
+			detail += " (" + ide + ")"
+		}
+		return detail
+	case aitool.AIToolTypeProjectConfig:
+		if tool.Agent != nil && len(tool.Agent.InstructionFiles) > 0 {
+			return strings.Join(fileBaseNames(tool.Agent.InstructionFiles), ", ")
+		}
+		return tool.ConfigPath
+	default:
+		return tool.ConfigPath
+	}
+}
+
+func writeJSONInventory(inventory *aitool.AIToolInventory, path string) error {
+	data, err := json.MarshalIndent(inventory, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(path, data, 0o644)
+}
+
+func redirectLogOutput(cmd *cobra.Command) {
+	logFile, _ := cmd.Root().PersistentFlags().GetString("log")
+	if logFile == "-" {
+		logger.MigrateTo(os.Stdout)
+	} else if logFile != "" {
+		logger.LogToFile(logFile)
+	} else {
+		logger.MigrateTo(io.Discard)
+	}
+}
+
+func fileBaseNames(paths []string) []string {
+	names := make([]string, len(paths))
+	for i, p := range paths {
+		names[i] = filepath.Base(p)
+	}
+	return names
+}
+
+// buildDiscoveryScope converts CLI --scope flag values to a DiscoveryScope.
+// Returns nil (all scopes) when no scopes are specified.
+func buildDiscoveryScope(scopes []string) (*aitool.DiscoveryScope, error) {
+	if len(scopes) == 0 {
+		return nil, nil
+	}
+	parsed := make([]aitool.AIToolScope, len(scopes))
+	for i, s := range scopes {
+		parsed[i] = aitool.AIToolScope(s)
+	}
+	return aitool.NewDiscoveryScope(parsed...)
+}

cmd/ai/main.go

@@ -0,0 +1,22 @@
+package ai
+
+import "github.com/spf13/cobra"
+
+func NewAICommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "ai",
+		Short: "AI tools usage discovery and analysis",
+		Long: `Discover and audit AI tool usage across the local development environment.
+
+AI coding agents, MCP servers, and extensions are often adopted by developers
+without centralized visibility, creating Shadow AI. This command group helps
+gain awareness of what AI tools are active, what permissions they hold, and
+what external services they connect to.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Help()
+		},
+	}
+
+	cmd.AddCommand(newDiscoverCommand())
+	return cmd
+}

docs/ai-discovery-dev.md

@@ -0,0 +1,93 @@
+# AI Tool Discovery: Developer Guide
+
+This document covers the internal structure of `pkg/aitool` for contributors who need to add new applications, CLI tools, IDE extensions, or modify discovery behavior.
+
+## Package layout
+
+| File | Purpose |
+|------|---------|
+| `model.go` | Core types: `AITool`, `AIToolType`, `AIToolScope`, inventory helpers |
+| `reader.go` | `AIToolReader` interface that all discoverers implement |
+| `registry.go` | `Registry` that wires discoverers and runs discovery, `DiscoveryConfig` |
+| `scope.go` | `DiscoveryScope` with prerequisite validation |
+| `mcp_config.go` | Shared MCP config parsing used by config-based discoverers |
+| `cli_common.go` | Shared CLI probe/verify pipeline used by CLI tool discoverers |
+| `sanitize.go` | Argument redaction for secret patterns |
+| `known_extensions.go` | Map of recognized AI IDE extension IDs |
+
+## Curated maps
+
+Several maps require manual updates when adding support for new tools.
+
+### `knownScopes` in `scope.go`
+
+Maps each `AIToolScope` to its `ScopeMetadata` (prerequisites like `RequiresHomeDir` or `RequiresProjectDir`). A new scope must be registered here or `NewDiscoveryScope` will reject it.
+
+### `knownAIExtensions` in `known_extensions.go`
+
+Maps lowercase VSIX extension IDs to display names. The IDE extension discoverer filters installed extensions against this map. To recognize a new AI extension, add its ID and display name here.
+
+### `ideDirNames` in `ai_extension.go`
+
+Maps IDE config directory names (e.g. `.vscode`, `.cursor`) to human readable IDE names. This is used to label which IDE an extension belongs to. Add an entry when supporting a new IDE distribution.
+
+### `argSecretPatterns` in `sanitize.go`
+
+List of CLI argument prefixes (e.g. `--token=`, `--api-key=`) that trigger value redaction. Add new patterns here if a tool uses a nonstandard secret flag.
+
+### `DefaultRegistry()` in `registry.go`
+
+Wires all built-in discoverers in a fixed order. Any new discoverer must be registered here.
+
+## Adding a new config-based app discoverer
+
+A config-based discoverer reads JSON configuration files from well-known filesystem paths. Examples: `claude_code.go`, `cursor.go`, `windsurf.go`.
+
+1. Create a new file (e.g. `newapp.go`) with a struct implementing `AIToolReader`.
+2. Define an app constant (e.g. `const newappApp = "newapp"`).
+3. In the factory function, resolve `HomeDir` from config (falling back to `os.UserHomeDir()`).
+4. In `EnumTools`, gate system work behind `config.ScopeEnabled(AIToolScopeSystem)` and project work behind `config.ScopeEnabled(AIToolScopeProject)`.
+5. Use `parseMCPAppConfig` and `emitMCPServers` from `mcp_config.go` if the app stores MCP servers in the standard `{"mcpServers": {...}}` JSON format.
+6. Register the factory in `DefaultRegistry()`.
+7. Add test fixtures under `fixtures/` and write tests following the pattern in existing `*_test.go` files.
+
+## Adding a new CLI tool discoverer
+
+A CLI tool discoverer searches `$PATH` for a binary, executes it with a version flag, and verifies the output matches a known pattern.
+
+1. Create a new file (e.g. `newtool.go`) with a struct implementing `CLIToolVerifier`.
+2. Implement `BinaryNames()` (candidate names to search), `VerifyArgs()` (flags to run), `VerifyOutput()` (regex to extract version), `DisplayName()`, and `App()`.
+3. Create a factory function that returns `&cliToolDiscoverer{verifier: &newVerifier{}, config: config}`.
+4. Register in `DefaultRegistry()`.
+5. Add a test case to `TestCLIVerifiers_VerifyOutput` in `cli_common_test.go`.
+
+## Adding a new IDE extension
+
+Add a single entry to `knownAIExtensions` in `known_extensions.go`. The key must be the lowercase VSIX extension ID (e.g. `publisher.extension-name`). No other code changes are needed.
+
+If the extension ships through a new IDE distribution not yet listed in `ideDirNames`, add the directory name mapping there as well.
+
+## Scope rules
+
+The `scope` field on emitted `AITool` entries must reflect where the configuration file physically lives, not which project it relates to.
+
+- Files under `~/.<app>/` or similar user-global directories are `system` scoped.
+- Files inside a project repository (e.g. `.mcp.json`, `.cursorrules`) are `project` scoped.
+
+For example, `~/.claude/projects/*/settings.json` lives inside the system-level `~/.claude/` directory, so tools discovered from it are `system` scoped even though the directory name contains "projects".
+
+## Shared MCP config parsing
+
+`mcp_config.go` provides types and helpers shared across apps that use the common `{"mcpServers": {...}}` JSON format:
+
+- `mcpServerEntry` represents a single server entry. It handles both `url` and `serverUrl` keys (Windsurf uses `serverUrl`). The `resolvedURL()` method normalizes this.
+- `mcpAppConfig` represents the top-level JSON structure. Extra fields like `permissions` and `model` are used only by Claude Code; other apps ignore them.
+- `parseMCPAppConfig(path)` reads and parses the file, logging a warning on parse errors.
+- `emitMCPServers(cfg, path, scope, app, handler)` iterates servers in deterministic order and emits `AITool` entries with sanitized args and env var names (values are never captured).
+- `detectTransport(entry)` infers the MCP transport from an explicit `type` field or falls back to heuristics (command present means stdio, URL with `/sse` means SSE, other URLs mean streamable HTTP).
+
+## Security invariants
+
+- Environment variable and header **values** are never stored. Only key names are recorded.
+- CLI arguments matching patterns in `argSecretPatterns` are redacted by `SanitizeArgs`.
+- No network calls are made during discovery. All data comes from local filesystem and `$PATH`.