Metadata-Version: 2.4
Name: canop
Version: 0.1.0
Summary: A fast, standalone security scanner designed to catch vulnerabilities written by AI.
Home-page: https://github.com/openbreach/canop
Author: CanoP Security
Author-email: canop.security@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CanoP CLI

[![PyPI version](https://badge.fury.io/py/canop-cli.svg)](https://badge.fury.io/py/canop-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A fast, standalone static analysis tool designed specifically to detect vulnerabilities introduced by AI coding assistants. CanoP analyzes your codebase locally to ensure that the code generated by AI is not just functionally correct, but demonstrably secure.

## Features

* **High Signal-to-Noise Ratio**: Traditional scanners produce overwhelming alerts. CanoP is tuned specifically for modern AI failure modes (such as SQL injection, unsafe reflection, and hardcoded secrets), ensuring that the alerts you see are actionable and high-priority.
* **Multi-Language Support**: Offers out-of-the-box analysis for Python, JavaScript, TypeScript, Java, Go, Ruby, and PHP, allowing you to secure full-stack applications with a single tool.
* **CI/CD Ready**: Designed to integrate directly into deployment pipelines. You can enforce security standards by configuring failure thresholds based on severity levels (e.g., failing builds on CRITICAL findings) and overall security scoring.
* **AI Prescriptions**: Rather than just pointing out flaws, CanoP automatically generates structured `fixes.json` payloads. These contain specific prompts designed to be fed back into Large Language Models (LLMs) for immediate, context-aware remediation.
* **Standardized Reporting**: Exports findings to standard JSON or SARIF (Static Analysis Results Interchange Format) for seamless integration with GitHub Advanced Security and enterprise vulnerability management platforms.

## Installation

CanoP is distributed as a standard Python package via PyPI. Install it globally in your environment using `pip`:

```bash
pip install canop
```

Verify the installation to ensure the CLI is available in your system path:

```bash
canop --version
```

## Quick Start

Initialize the configuration files in your repository. This command creates a `.canop.yml` policy file and a `.canopignore` file to exclude noisy directories like `node_modules` or `venv` from the scan:

```bash
canop init
```

Run a comprehensive security scan against your current directory. The scanner evaluates your code against the internal rule engine and outputs a detailed table with a final security score:

```bash
canop scan .
```

Scan only files that have been modified in git. This dramatically reduces scan time and is ideal for pre-commit hooks, ensuring new code is secure before it is committed:

```bash
canop scan . --changed
```

## Advanced Usage

### Continuous Integration / Continuous Deployment (CI/CD)

CanoP is built to act as a security gatekeeper in automated deployment pipelines (such as GitHub Actions or GitLab CI). You can configure the scanner to return a non-zero exit code—which automatically fails the build—if specific security criteria are not met.

```bash
# Fail the deployment pipeline if any CRITICAL or HIGH vulnerabilities are found
canop scan . --fail-on HIGH

# Fail the deployment pipeline if the aggregate security score falls below 85
canop scan . --min-score 85
```

### Exporting Results

For teams that require historical tracking, auditing, or integration with external systems, CanoP supports multiple output formats.

```bash
# Export the raw native Python dictionary data to a standard JSON file for custom parsing
canop scan . --json-out results.json

# Export to SARIF (Static Analysis Results Interchange Format).
# Uploading this file to GitHub allows GitHub to display the vulnerabilities inline in Pull Requests.
canop scan . --sarif results.sarif
```

### Automated Remediation

CanoP extracts the remediation metadata from its rules engine to generate prompts that instruct AI coding assistants on exactly how to fix the detected vulnerabilities.

```bash
# Generate a fixes.json file containing actionable prompts for your LLM
canop scan . --prescriptions fixes.json
```

## Configuration

CanoP behavior can be codified using a `.canop.yml` file placed in the root of your project. This file acts as a centralized security policy, ensuring all developers and CI/CD pipelines adhere to the same thresholds.

```yaml
# .canop.yml
# Require a minimum security grade to pass the pipeline
min_grade: B

# Treat these specific severity levels as pipeline failures
fail_on:
  - CRITICAL
  - HIGH

# Ignore specific paths from being scanned
ignore:
  - "tests/**"
  - "docs/**"

# Allow a certain number of findings before returning a non-zero exit code (0 = strictly unlimited)
max_findings: 0
```

You can also rely on `.canopignore` to define specific files or directories that the scanner should skip. It utilizes standard glob patterns, functioning identically to `.gitignore`.

## Local Development

If you wish to contribute to the CLI or test changes locally, clone the repository and install it in editable mode. Editable mode maps the `canop` terminal command directly to your live source code.

```bash
git clone https://github.com/your-org/canop-cli.git
cd canop-cli
pip install -e .
```

### Rule Development

Security rules are defined in the standard Semgrep YAML format and are located within `canop/rules/*.yml`. Please see `CONTRIBUTING.md` for comprehensive guidelines on how to structure, test, and submit new rules to expand the scanner's detection capabilities.

## Support

If you find any bugs, have feature requests, or need general help, please open an issue on GitHub or contact us directly at canop.security@gmail.com.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
