Content
# mcp-scanner
A security scanner for Model Context Protocol servers. It scans live servers,
source trees, and packages, and reports both findings and coverage gaps.
`SAFE` requires every required analyzer to finish without a reported coverage
gap:
```
COMPLETED + SAFE required analysis ran, nothing blocking
COMPLETED + UNSAFE required analysis ran, something blocking
PARTIAL + UNKNOWN an analyzer could not finish
ERROR + UNKNOWN an analyzer failed
SKIPPED + UNKNOWN no analyzer produced usable analysis
```
Timeouts, crashes, unexplained files, and missing statuses downgrade the scan.
An analyzer error is never self-excusing; only an explicit best-effort policy
can exempt it. A known limitation is that any recorded file-skip reason accounts
for all skipped files, so some incomplete file scans can still be `SAFE`.
## Install
```sh
go install github.com/revinand/mcp-scanner/cmd/mcp-scanner@latest
```
Signature matching requires libyara and a tagged build:
```sh
# Debian, Ubuntu
sudo apt install libyara-dev pkg-config
# Fedora, RHEL
sudo dnf install yara-devel pkgconf-pkg-config
# macOS
brew install yara pkg-config
```
```sh
make build-yara
```
See the [YARA installation guide](https://yara.readthedocs.io/en/stable/gettingstarted.html)
for source builds. If `/usr/local/lib` is outside the linker path, run
`sudo ldconfig` or set `LD_LIBRARY_PATH=/usr/local/lib`. Builds without the
tag report YARA as unavailable.
## Use
Scan a remote server:
```sh
mcp-scanner remote https://mcp.example.com/mcp
```
Scan a trusted stdio server as a child process:
```sh
mcp-scanner stdio -- npx -y @example/mcp-server
```
This runs the target on your machine with your privileges. For untrusted code,
use `source` or `package`, which do not execute it. `runtime stdio` runs only an
absolute, statically linked ELF executable in a container and needs a trusted
snapshot.
Scan the servers declared in your MCP client configuration:
```sh
mcp-scanner known-configs --run
```
`--run` scans remote entries. Stdio entries are skipped unless you also pass
`--include-stdio`, and any skipped stdio entry makes the command exit 3.
Scan a source tree, or a published package:
```sh
mcp-scanner source ./my-mcp-server
mcp-scanner package npm:@example/mcp-server@1.4.0
```
Gate a pipeline:
```sh
mcp-scanner remote https://mcp.example.com/mcp --format sarif --output results.sarif --fail-on high
```
Exit codes:
| Code | Meaning |
|---|---|
| 0 | scan completed, policy passed |
| 1 | bad flags or configuration |
| 2 | scan completed, policy failed |
| 3 | scan could not determine an answer |
| 4 | the scanner itself broke |
`--fail-on` defaults to `high`, so a pipeline that never sets it still stops
on a high or critical finding. Pass `--fail-on none` to report without
gating.
Treat exit code 3 as a pipeline failure. It means the scan did not finish.
## What it checks
- MCP protocol conformance, capability declarations against actual behaviour,
and how the server handles malformed input
- Authentication, token validation and session binding
- Prompt injection, tool poisoning, hidden Unicode and credential harvesting
in the text a server hands a model
- Source-to-sink dataflow across files, in Go, Python, JavaScript, TypeScript,
Java and Rust
- Mismatch between what a tool says it does and what its handler reaches
- Dependency vulnerabilities and package contents, without running install
scripts
- Optional sandboxed confirmation of static findings
- Optional model-assisted review that supplements deterministic evidence
## Scanning safely
By default, the scanner discovers capabilities without invoking real tools.
```sh
--active-probes none connect and read declarations
--active-probes safe also send malformed protocol messages a correct server must reject
--active-probes tool-calls permit tools named with --allow-tool-call
```
`safe` is the default. Its `tools/call` probes use an invalid name or a name
that does not exist, which a conforming server rejects before dispatch.
A loose server may dispatch such a request before validating the name. No
setting invokes arbitrary declared tools on a live server or sends intentionally
destructive requests. The runtime analyzer can invoke declared tools only inside
its sandbox.
## Documentation
- [Architecture](docs/architecture.md)
- [Analyzers](docs/analyzers/README.md)
- [Threat model](docs/threat-model.md)
- [Compatibility](docs/compatibility.md)
- [Result schema](docs/result-schema.md)
- [Command line](docs/cli.md)
- [HTTP API](docs/api.md)
## Development
```sh
make check # gofmt, vet, test, race, vulnerability scan, version check
make build
```
Three rules hold the design together: `SAFE` must mean the analysis ran,
every finding carries evidence, and every analyzer reports what it did not
look at.
## Security
Report vulnerabilities privately. See [SECURITY.md](SECURITY.md).
## License
Apache License 2.0. See [LICENSE](LICENSE). Binaries also include the third-party
components listed in [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).
MCP Store