Introduction
Police of Code is a security-focused static analysis platform designed to detect dangerous programming patterns, architectural weaknesses, and high-risk security antipatterns before code reaches production environments.
The tool is intentionally positioned between educational tooling and enterprise-grade security scanners. It is suitable for individual developers, teams, CI pipelines, and security training environments.
Security Philosophy
The project is built around a prevention-first mindset. Security is treated as a development responsibility rather than a post-incident process.
- Vulnerabilities are cheaper to fix before deployment
- Security feedback must be actionable and understandable
- Rules must explain risk, not just detect it
- Determinism is critical for trust
Architecture Overview
The system is composed of independent modules connected through stable contracts. This design allows each component to evolve without breaking others.
| Layer | Module | Primary Responsibility |
|---|---|---|
| Interface | CLI | Execution control and configuration |
| Parsing | Parser | AST generation and normalization |
| Analysis | Analyzer | Context construction and traversal |
| Detection | Rule Engine | Security policy enforcement |
| Output | Reporter | Human-readable findings |
CLI
The CLI is the primary user interface. It supports scanning directories, severity thresholds, configuration files, and CI-friendly exit codes.
police-of-code scan ./src --severity critical
Analyzer
The analyzer performs AST traversal while maintaining contextual metadata such as scope hierarchies, variable lifetimes, and call relationships.
Parser
The parser converts JavaScript source files into normalized AST structures, ensuring consistent analysis across syntax variants.
- Modern ECMAScript support
- Deterministic node identifiers
- Syntax normalization
Rule Engine
The rule engine orchestrates detection logic using isolated, composable rules. Each rule operates independently to ensure system stability.
| Phase | Description |
|---|---|
| Initialization | Rule metadata validation |
| Execution | AST node inspection |
| Aggregation | Finding normalization |
Rules
Rules represent enforceable security laws. Violations generate structured findings containing severity, location, and remediation guidance.
- hardcodedSecrets — embedded credentials
- sqlInjection — unsafe query construction
- emptyCatch — suppressed error handling
- longFunctions — maintainability risk
Reporter
The reporter formats findings for console output and future integrations such as JSON, SARIF, or dashboards.
Personality
The personality module defines tone and language, reinforcing the policing metaphor while remaining professional.
Examples
The examples directory contains intentionally vulnerable code used for testing, education, and demonstrations.
Tests
Automated tests validate analyzer correctness, rule accuracy, and regression prevention.