https://github.com/zcaceres/crt-cli
Search Certificate Transparency logs via crt.sh — CLI, MCP server, and TypeScript library
https://github.com/zcaceres/crt-cli
Last synced: 3 months ago
JSON representation
Search Certificate Transparency logs via crt.sh — CLI, MCP server, and TypeScript library
- Host: GitHub
- URL: https://github.com/zcaceres/crt-cli
- Owner: zcaceres
- Created: 2026-03-14T02:04:42.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-14T22:15:06.000Z (4 months ago)
- Last Synced: 2026-03-15T07:42:50.280Z (4 months ago)
- Language: TypeScript
- Size: 57.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# crt-cli
Search [Certificate Transparency](https://certificate.transparency.dev/) logs via [crt.sh](https://crt.sh). Available as a CLI, an MCP server, or a TypeScript library.
Built with [Bun](https://bun.sh).
## Install
```bash
bun install
```
## CLI
```bash
crt [args] [flags]
```
### Commands
**search** — Search CT logs for certificates matching a domain.
```bash
crt search example.com
crt search example.com example.org
crt search example.com -w -e -d
crt search example.com --format csv
```
| Flag | Alias | Description |
|------|-------|-------------|
| `--wildcard` | `-w` | Prefix query with `%.` for subdomain search |
| `--exclude-expired` | `-e` | Exclude expired certificates |
| `--dedupe` | `-d` | Deduplicate results by serial number |
| `--format ` | `-f` | Output format: `json` (default), `table`, `csv`, `subdomains` |
**subdomains** — Find unique subdomains for a domain. Shortcut for `search -w --format subdomains`.
```bash
crt subdomains example.com
crt subdomains example.com -e
```
**cert** — Look up a specific certificate by its crt.sh ID.
```bash
crt cert 12345678
```
### Global flags
| Flag | Alias | Description |
|------|-------|-------------|
| `--version` | `-V` | Print version |
| `--describe` | | Output JSON schema of all commands (see below) |
| `--help` | `-h` | Show help |
### Machine-readable description
```bash
crt --describe
```
Outputs a JSON schema of all commands, arguments, and flags. Useful for agent tool discovery.
## MCP Server
The MCP server exposes the same functionality over the [Model Context Protocol](https://modelcontextprotocol.io/) via stdio transport.
```bash
bun run src/mcp.ts
```
### Tools
| Tool | Description |
|------|-------------|
| `search_certificates` | Search CT logs. Accepts `domain` or `domains` (array), `wildcard`, `excludeExpired`, `dedupe`, `format`. |
| `find_subdomains` | Find unique subdomains for a domain (wildcard search). |
| `lookup_cert` | Look up a certificate by crt.sh ID. |
### Configuration
Add to your MCP client config:
```json
{
"mcpServers": {
"crt-sh": {
"command": "bun",
"args": ["run", "/path/to/crt-cli/src/mcp.ts"]
}
}
}
```
## Library
Import directly into your TypeScript/Bun project:
```ts
import {
searchCertificates,
extractSubdomains,
dedupeBySerial,
createServer,
} from "crt-cli";
```
### API
```ts
// Search for certificates
const certs = await searchCertificates("example.com", {
wildcard: true,
excludeExpired: true,
});
// Extract unique subdomains
const subs = extractSubdomains(certs);
// Deduplicate by serial number
const unique = dedupeBySerial(certs);
// Embed the MCP server in your own application
const server = createServer();
```
### Exports
| Export | Type | Description |
|--------|------|-------------|
| `searchCertificates` | function | Query crt.sh and return parsed results |
| `dedupeBySerial` | function | Deduplicate entries by serial number |
| `extractSubdomains` | function | Extract sorted unique subdomains from entries |
| `buildUrl` | function | Build a crt.sh query URL |
| `validateCertId` | function | Validate a certificate ID string |
| `validateDomain` | function | Validate a domain string (rejects invalid characters, missing dots, etc.) |
| `CrtShError` | class | Error class with code (`NETWORK_ERROR`, `SERVER_ERROR`, `HTTP_ERROR`, `PARSE_ERROR`, `VALIDATION_ERROR`, `INVALID_ARG`, `INVALID_DOMAIN`) |
| `formatJson` | function | Format entries as pretty-printed JSON |
| `formatTable` | function | Format entries as an ASCII table |
| `formatCsv` | function | Format entries as RFC 4180 CSV |
| `formatSubdomains` | function | Format subdomains as a newline-separated list |
| `formatMultiDomainJson` | function | Format multi-domain results as grouped JSON |
| `formatMultiDomainResults` | function | Format multi-domain results with domain headers |
| `formatError` | function | Format an error as JSON |
| `searchMultipleDomains` | function | Search multiple domains with sequential delay |
| `MultiDomainResult` | type | Result type for multi-domain search |
| `createServer` | function | Create an MCP server instance |
| `CrtShEntrySchema` | Zod schema | Schema for a single crt.sh entry |
| `CrtShResponseSchema` | Zod schema | Schema for an array of entries |
| `CrtShEntry` | type | TypeScript type for a certificate entry |
| `CrtShResponse` | type | TypeScript type for the response array |
## Testing
```bash
bun test
```
150+ tests across 11 files covering the CLI, API, formatters, argument parsing, schema validation, library exports, MCP server, CSV integration, and multi-domain pipelines.
## Linting
```bash
bun run check # lint and format check
bun run check:fix # auto-fix
```
Uses [Biome](https://biomejs.dev/) for linting and formatting.
## CI/CD
GitHub Actions runs lint and tests on every push and PR to `main`. On push to `main`, if the version in `package.json` has changed, it builds standalone binaries for Linux (x64, arm64), macOS (x64, arm64), and Windows (x64) and creates a GitHub release.