# Detectors Reference
Repotoire includes **108 detectors** across multiple categories. All detectors run locally with no external API dependencies (except optional AI fixes).
---
## Table of Contents
- [Security Detectors](#security-detectors)
- [Code Smells](#code-smells)
- [Architecture & Design](#architecture--design)
- [AI Code Pattern Detection](#ai-code-pattern-detection)
- [Performance](#performance)
- [Code Quality](#code-quality)
- [Framework-Specific](#framework-specific)
- [External Tool Integration](#external-tool-integration)
- [Configuration](#configuration)
---
## Security Detectors
These detectors find security vulnerabilities in your code.
| `SQLInjectionDetector` | Detects SQL queries with string interpolation/concatenation (CWE-89) | Critical |
| `CommandInjectionDetector` | Finds shell command injection via `os.system()`, `subprocess` with user input | Critical |
| `PathTraversalDetector` | Detects directory traversal attacks (`../` in file paths) | Critical |
| `EvalDetector` | Finds dangerous `eval()`, `exec()`, and code execution with user input | Critical |
| `PickleDeserializationDetector` | Detects unsafe pickle/yaml/marshal deserialization | Critical |
| `XssDetector` | Cross-site scripting via unescaped HTML output | High |
| `SsrfDetector` | Server-side request forgery via user-controlled URLs | High |
| `XxeDetector` | XML External Entity injection in XML parsers | High |
| `InsecureDeserializeDetector` | Unsafe deserialization in multiple formats | High |
| `NosqlInjectionDetector` | NoSQL injection in MongoDB/Mongoose queries | High |
| `PrototypePollutionDetector` | JavaScript prototype pollution attacks | High |
| `SecretDetector` | Hardcoded API keys, passwords, tokens in code | High |
| `CleartextCredentialsDetector` | Passwords/secrets stored in plain text | High |
| `InsecureCryptoDetector` | Weak cryptographic algorithms (MD5, SHA1, DES) | Medium |
| `InsecureRandomDetector` | Predictable random number generation | Medium |
| `JwtWeakDetector` | Weak JWT configurations (none algorithm, weak secrets) | Medium |
| `InsecureCookieDetector` | Cookies without Secure/HttpOnly/SameSite flags | Medium |
| `CorsMisconfigDetector` | Overly permissive CORS configurations | Medium |
| `HardcodedIpsDetector` | Hardcoded IP addresses | Low |
| `LogInjectionDetector` | Log injection vulnerabilities | Low |
| `TaintDetector` | Graph-based taint analysis tracking data flow | Varies |
| `UnsafeTemplateDetector` | Unsafe template rendering (Jinja2, EJS, etc.) | High |
---
## Code Smells
Classic code smells that indicate design problems.
| `GodClassDetector` | Classes with too many methods, lines, or complexity | High |
| `LongMethodsDetector` | Functions that are too long (default: >50 lines) | Medium |
| `LongParameterListDetector` | Functions with too many parameters (default: >6) | Medium |
| `DeepNestingDetector` | Deeply nested code blocks | Medium |
| `MessageChainDetector` | Long method chains (`a.b.c.d.e()`) | Low |
| `FeatureEnvyDetector` | Methods that use more data from other classes | Medium |
| `InappropriateIntimacyDetector` | Classes that access each other's internals excessively | Medium |
| `DataClumpsDetector` | Groups of data that appear together frequently | Low |
| `MiddleManDetector` | Classes that only delegate to other classes | Low |
| `LazyClassDetector` | Classes that don't do enough | Low |
| `RefusedBequestDetector` | Subclasses that don't use inherited methods | Low |
| `ShotgunSurgeryDetector` | Changes that require many small edits across files | Medium |
| `DuplicateCodeDetector` | Near-duplicate code blocks | Medium |
---
## Architecture & Design
Detectors that analyze the overall architecture of your codebase.
| `CircularDependencyDetector` | Circular imports using Tarjan's SCC algorithm | High |
| `ArchitecturalBottleneckDetector` | Files/classes with high betweenness centrality | Medium |
| `DegreeCentralityDetector` | Hub nodes with excessive connections | Medium |
| `ModuleCohesionDetector` | Modules with low internal cohesion | Medium |
| `CoreUtilityDetector` | Identifies core vs utility code | Info |
| `InfluentialCodeDetector` | Code that affects many other parts | Info |
---
## AI Code Pattern Detection
Detectors specifically designed to find patterns common in AI-generated code.
| `AIComplexitySpikeDetector` | Sudden complexity increases (AI tends to generate complex solutions) | Medium |
| `AIChurnDetector` | High churn rate (AI code often gets rewritten quickly) | Medium |
| `AIBoilerplateDetector` | Excessive boilerplate patterns typical of AI | Low |
| `AIDuplicateBlockDetector` | Near-duplicate blocks from copy-paste AI suggestions | Medium |
| `AINamingPatternDetector` | Generic naming patterns (`data`, `result`, `temp`) | Low |
| `AIMissingTestsDetector` | New functions without corresponding tests | Medium |
---
## Performance
Detectors that find performance issues.
| `NPlusOneDetector` | N+1 query patterns in database access | High |
| `SyncInAsyncDetector` | Blocking I/O calls in async functions | High |
| `RegexInLoopDetector` | Regex compilation inside loops | Medium |
| `StringConcatLoopDetector` | String concatenation in loops (use StringBuilder) | Medium |
| `InfiniteLoopDetector` | Potential infinite loops | High |
| `RegexDosDetector` | ReDoS-vulnerable regular expressions | Medium |
---
## Code Quality
General code quality issues.
| `DeadCodeDetector` | Unreachable/unused code (graph-based analysis) | Low |
| `UnreachableCodeDetector` | Code after return/throw statements | Low |
| `DeadStoreDetector` | Variables assigned but never used | Low |
| `EmptyCatchDetector` | Empty catch/except blocks | Medium |
| `BroadExceptionDetector` | Catching base Exception class | Low |
| `TodoScanner` | TODO/FIXME/HACK comments | Info |
| `CommentedCodeDetector` | Commented-out code blocks | Low |
| `MagicNumbersDetector` | Magic numbers without constants | Low |
| `LargeFilesDetector` | Files exceeding line thresholds | Low |
| `MissingDocstringsDetector` | Public functions without docstrings | Low |
| `UnusedImportsDetector` | Imports that are never used | Low |
| `WildcardImportsDetector` | `from x import *` patterns | Low |
| `GlobalVariablesDetector` | Global variable usage | Low |
| `MutableDefaultArgsDetector` | Mutable default arguments in Python | Medium |
| `SingleCharNamesDetector` | Single-character variable names | Low |
| `BooleanTrapDetector` | Boolean parameters without clear meaning | Low |
| `InconsistentReturnsDetector` | Functions with inconsistent return types | Medium |
| `HardcodedTimeoutDetector` | Hardcoded timeout values | Low |
| `ImplicitCoercionDetector` | JavaScript implicit type coercion | Low |
| `DebugCodeDetector` | Debug statements left in code | Low |
| `TestInProductionDetector` | Test code patterns in production files | Medium |
---
## Async & Promise Patterns
| `MissingAwaitDetector` | Async function calls without await | High |
| `UnhandledPromiseDetector` | Promises without .catch() or try/catch | Medium |
| `CallbackHellDetector` | Deeply nested callbacks | Medium |
| `GeneratorMisuseDetector` | Incorrect generator/yield usage | Medium |
---
## Framework-Specific
| `ReactHooksDetector` | React hooks rules violations | High |
| `DjangoSecurityDetector` | Django-specific security issues | High |
| `ExpressSecurityDetector` | Express.js security misconfigurations | High |
| `GHActionsInjectionDetector` | GitHub Actions command injection | Critical |
---
## External Tool Integration
These detectors wrap external tools and require those tools to be installed.
### Python Tools
| `BanditDetector` | [Bandit](https://bandit.readthedocs.io/) | Python security analysis |
| `RuffLintDetector` | [Ruff](https://github.com/astral-sh/ruff) | Fast Python linting (100x faster than Pylint) |
| `RuffImportDetector` | Ruff | Unused import detection |
| `MypyDetector` | [Mypy](https://mypy.readthedocs.io/) | Python type checking |
| `RadonDetector` | [Radon](https://radon.readthedocs.io/) | Python complexity metrics |
| `VultureDetector` | [Vulture](https://github.com/jendrikseipp/vulture) | Dead Python code detection |
| `PylintDetector` | [Pylint](https://pylint.org/) | Comprehensive Python linting |
### JavaScript/TypeScript Tools
| `ESLintDetector` | [ESLint](https://eslint.org/) | JavaScript/TypeScript linting |
| `TscDetector` | TypeScript | TypeScript type checking |
| `NpmAuditDetector` | npm | Dependency vulnerability scanning |
### Cross-Language Tools
| `SemgrepDetector` | [Semgrep](https://semgrep.dev/) | Security pattern matching |
| `JscpdDetector` | [jscpd](https://github.com/kucherenko/jscpd) | Cross-language duplicate detection |
---
## Configuration
### Per-Project Configuration
Configure detectors in `repotoire.toml`:
```toml
[detectors.god-class]
enabled = true
thresholds = { method_count = 30, loc = 600 }
[detectors.long-parameter-list]
thresholds = { max_params = 8 }
[detectors.sql-injection]
severity = "high" # Downgrade from critical
[detectors.magic-numbers]
enabled = false # Disable entirely
```
### Detector Names
Use kebab-case in config. These formats are equivalent:
- `god-class`
- `god_class`
- `GodClassDetector`
### Threshold Options
Common threshold options by detector:
| `god-class` | `method_count` (default: 20), `loc` (default: 500), `complexity` (default: 100) |
| `long-parameter-list` | `max_params` (default: 6) |
| `long-methods` | `max_lines` (default: 50) |
| `deep-nesting` | `max_depth` (default: 4) |
| `message-chain` | `max_chain` (default: 4) |
| `large-files` | `max_lines` (default: 1000) |
| `complexity` | `threshold` (default: 10) |
### Inline Suppression
Suppress specific findings with comments:
```python
# repotoire: ignore
def legacy_function():
pass
```
```javascript
// repotoire: ignore
const query = `SELECT * FROM ${table}`; // Suppressed
```
Works with `#`, `//`, `/* */`, and `--` comment styles.
### CLI Flags
```bash
# Skip specific detectors
repotoire analyze . --skip-detectors god-class,magic-numbers
# Run only specific detectors
repotoire analyze . --only-detectors sql-injection,secrets
# Include external tools (slower)
repotoire analyze . --thorough
# Show only high+ severity
repotoire analyze . --severity high
```
---
## Running Detectors
### Quick Start
```bash
# Run all default detectors (graph-based, fast)
repotoire analyze .
# Run with external tools (slower, more thorough)
repotoire analyze . --thorough
```
### Detector Engine Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ DetectorEngine │
│ - Runs independent detectors in parallel (rayon) │
│ - Runs dependent detectors sequentially │
│ - Aggregates and deduplicates findings │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Graph-based │ │ File-based │ │ External Tool │
│ (CircularDep, │ │ (Secrets, │ │ (Bandit, Ruff, │
│ GodClass, etc.) │ │ SQL Inj.) │ │ ESLint, etc.) │
└──────────────────┘ └──────────────┘ └──────────────────┘
```
Graph-based detectors query the knowledge graph for structural patterns. File-based detectors scan source files directly. External tool detectors wrap CLI tools via subprocess.
### Performance
| Graph-based | Very fast (~100-400 files/sec) | Always |
| File-based | Fast (~50-100 files/sec) | Always |
| External tools | Slower (depends on tool) | `--thorough` flag |
---
## Writing Custom Detectors
Implement the `Detector` trait:
```rust
use repotoire_cli::detectors::{Detector, DetectorConfig};
use repotoire_cli::graph::GraphStore;
use repotoire_cli::models::Finding;
use anyhow::Result;
pub struct MyDetector {
config: DetectorConfig,
}
impl Detector for MyDetector {
fn name(&self) -> &str {
"my-detector"
}
fn description(&self) -> &str {
"Detects something important"
}
fn detect(&self, graph: &GraphStore) -> Result<Vec<Finding>> {
let mut findings = Vec::new();
// Query the graph
// Analyze patterns
// Create findings
Ok(findings)
}
}
```
Register in `DetectorEngineBuilder`:
```rust
let engine = DetectorEngineBuilder::new()
.detector(Arc::new(MyDetector::new()))
.build();
```