Discovery Scanner

TrustTrace includes a filesystem discovery scanner that identifies AI agents and MCP servers in your codebase without requiring you to know where they are in advance. Discovery is the first step in a complete AI security posture assessment.

What Discovery Finds

MCP Configuration Files

The scanner identifies MCP server configuration files by filename pattern and content analysis.

High confidence detections (by filename): mcp.json, mcp.yaml, mcp.yml, .mcp.json, .mcp.yaml, claude_desktop_config.json, mcp-config.json, mcp-config.yaml, mcp-servers.json, mcp-servers.yaml

Medium confidence detections (by content): config.json, config.yaml, settings.json containing an mcpServers key.

For each detected configuration, the scanner reports the file path, number of MCP servers defined, and confidence level.

AI Agent Files

The scanner walks Python files and identifies agent definitions by import signatures, tool patterns, and LLM instantiation.

Detection signals: Framework imports (langchain, autogen, crewai, openai, anthropic), tool definitions (@tool decorator, tools=[ pattern), and LLM instantiation (ChatOpenAI, ChatAnthropic, llm = patterns).

Framework Signatures

The scanner reads dependency files to identify AI framework versions across your project. Supported formats: requirements.txt, pyproject.toml, package.json, Pipfile.

Current Detection Scope

Detected frameworks (Python import scanning): LangChain, AutoGen, CrewAI, OpenAI Assistants, Anthropic agents, FastAPI agent patterns.

Detected frameworks (requirements file scanning only, not import scanning): LlamaIndex, Haystack, Semantic Kernel, Ollama.

Not currently detected: JavaScript and TypeScript agent frameworks, Go-based agent implementations, Docker Compose agent definitions.

Detection scope will expand in future releases.

Running Discovery

Command line

trusttrace-discover [path] [options]

Arguments:

path                Directory to scan (default: current directory)

Options:

--output            Output format: text (default) or json
--max-depth         Maximum directory depth (default: 10)
--exclude           Additional directories to exclude (repeatable)
--min-confidence    Minimum confidence: MEDIUM (default) or HIGH

Examples:

Scan the current directory:

trusttrace-discover .

Scan with JSON output:

trusttrace-discover /path/to/repo --output json

HIGH confidence results only:

trusttrace-discover . --min-confidence HIGH

Exclude additional directories:

trusttrace-discover . --exclude tests --exclude fixtures

Exit codes

0   Scan completed (even if nothing found)
1   Path does not exist or is not a directory
2   Scan error

Default excluded directories

.git, .venv, venv, node_modules, pycache, .pytest_cache, dist, build, .next, .turbo, coverage

How Discovery Interacts with Assessment

The --discover flag scans the parent directory

The --discover flag on trusttrace-assess scans the parent directory of the specified config file, not the current working directory. For example:

trusttrace-assess ./configs/prod.json --discover
# Scans ./configs/ for additional agents and MCP servers

To scan your full repository, run trusttrace-discover separately first, then pass the target config to trusttrace-assess:

trusttrace-discover . --output json
trusttrace-assess ./configs/prod.json --discover

TT-DISC-001 and declared agent inventory

TT-DISC-001 fires for any agent or MCP server found by discovery that is not present in your declared agent inventory. Your declared inventory is set during the trusttrace intake interview.

On a first run without a completed intake, all discovered assets will generate TT-DISC-001 findings. This is expected behavior. The recommended sequence for a new environment is:

Step 1: Run trusttrace-discover to build an inventory of what exists in your codebase.

Step 2: Run the trusttrace intake interview to declare your authorized agents.

Step 3: Run trusttrace-assess with --discover to assess your declared agents and flag any undeclared ones.

Assessment JSON output with discovery

When --discover is used, the assessment JSON output includes an optional discovery_summary field:

{
  "discovery_summary": {
    "mcp_configs": [...],
    "agent_files": [...],
    "framework_signatures": [...],
    "total_files_scanned": 312,
    "scan_duration_seconds": 1.4
  }
}

This field is absent when --discover is not used. Consumers of the JSON output should treat it as optional.

GitHub Action Integration

The TrustTrace GitHub Action supports discover and discover-and-assess modes. Discovery mode finds all MCP configs and agent files without requiring you to specify their paths.

- name: TrustTrace Discover and Assess
  uses: trusttrace-io/trusttrace-action@v1
  with:
    mode: discover-and-assess
    path: .
    severity-threshold: HIGH
    output-format: sarif

- name: Upload to GitHub Code Scanning
  uses: actions/upload-sarif@v3
  if: always()
  with:
    sarif_file: ${{ steps.trusttrace.outputs.sarif-file }}

See the GitHub Action documentation for full usage details. Note: discover-and-assess mode is available in trusttrace-action v1.1 and later.

Discovery Findings

TT-DISC-001: Undocumented AI Agent or MCP Server Detected

Severity: MEDIUM OWASP: LLM03 (Supply Chain) CoSAI: T11, IIC

An AI agent or MCP server was found in the codebase that is not present in the organization's declared agent inventory. Undocumented agents represent unreviewed attack surface and gaps in security oversight.

Remediation: Add all discovered agents and MCP servers to your agent inventory. Review each for compliance with your security policies. Require security review before new agents are deployed.

Output Example

TrustTrace Discovery Report
Scanned: /path/to/repo
Duration: 1.4s
Files scanned: 312

MCP Configurations Found (3):
  HIGH mcp_json: ./mcp-config.json (4 servers)
  HIGH claude_desktop: ./claude_desktop_config.json (2 servers)
  MEDIUM unknown: ./config.json (1 server)

AI Agent Files Found (5):
  HIGH [langchain]: ./agents/research_agent.py
    Imports: langchain.agents, langchain.tools
    Has tools: yes  Has LLM: yes
  HIGH [crewai]: ./crew/analysis_crew.py
    Imports: crewai
    Has tools: yes  Has LLM: yes

Framework Signatures:
  langchain 0.2.1: detected in 3 files
  anthropic 0.25.0: detected in 1 file

Summary: Found 3 MCP configurations (7 total servers) and 5 agent files across 2 frameworks in 312 files scanned.