depaudit-cli/README.md

# DepAudit CLI

A comprehensive CLI tool that audits project dependencies across multiple languages for security vulnerabilities, outdated packages, license compliance issues, and unused dependencies.

## Features

- **Multi-language support**: JavaScript/Node.js, Python, Go, Rust, Java/Maven
- **Security vulnerability scanning**: Query OSV and NVD databases for CVEs
- **Outdated package detection**: Check for newer versions on package registries
- **License compliance checking**: Validate against allowlist/blocklist
- **Unused dependency detection**: Find dependencies that aren't imported
- **Multiple output formats**: Table (with colors), JSON, or quiet mode
- **CI/CD integration**: Generate GitHub Actions and GitLab CI configurations

## Installation

### From PyPI

```bash
pip install depaudit-cli
```

### From Source

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

### Using pipx

```bash
pipx install depaudit-cli
```

## Quick Start

Audit the current directory:

```bash
depaudit audit .
```

Audit a specific project:

```bash
depaudit audit /path/to/project
```

Output as JSON:

```bash
depaudit audit . --format json --output results.json
```

Skip specific checks:

```bash
depaudit audit . --skip-vulnerabilities --skip-licenses
```

Filter by severity:

```bash
depaudit audit . --severity high
```

## Supported Languages

| Language | Dependency Files |
|----------|-----------------|
| JavaScript/Node.js | `package.json`, `package-lock.json`, `yarn.lock` |
| Python | `requirements.txt`, `setup.py`, `pyproject.toml`, `Pipfile` |
| Go | `go.mod` |
| Rust | `Cargo.toml`, `Cargo.lock` |
| Java/Maven | `pom.xml`, `build.gradle` |

## Usage

### Command Options

| Option | Description |
|--------|-------------|
| `--format` | Output format: `table`, `json`, or `quiet` |
| `--output` | Write output to file |
| `--no-color` | Disable colored output |
| `--no-cache` | Disable API response caching |
| `--severity` | Minimum severity: `critical`, `high`, `medium`, `low`, `all` |
| `--skip-vulnerabilities` | Skip CVE vulnerability scanning |
| `--skip-outdated` | Skip outdated package checking |
| `--skip-licenses` | Skip license compliance checking |
| `--skip-unused` | Skip unused dependency detection |
| `--verbose` | Enable verbose output |

### CI/CD Generation

Generate GitHub Actions workflow:

```bash
depaudit generate-cicd github --schedule "0 0 * * 0"
```

Generate GitLab CI configuration:

```bash
depaudit generate-cicd gitlab
```

## Configuration

Create a `.depauditrc` file in your project root:

```yaml
output:
  format: table
  color: true
  verbosity: info

vulnerabilities:
  enabled: true
  severity_filter: all
  api: osv
  cache_ttl: 86400

licenses:
  enabled: true
  allowlist:
    - MIT
    - Apache-2.0
    - BSD-3-Clause
  blocklist:
    - GPL-3.0
    - AGPL-3.0

cicd:
  fail_on:
    - critical
    - high
```

## Output Formats

### Table Output

```
============================================================
DepAudit Report
============================================================
Scanned Files: 5
Scan Duration: 2.45s

[VULNERABILITIES]
+-----------+-------------------------+---------+--------+--------+
| Severity  | Package                 | Current | Fixed  | ID     |
+-----------+-------------------------+---------+--------+--------+
| CRITICAL  | lodash                  | 4.17.15 | 4.17.21| CVE... |
+-----------+-------------------------+---------+--------+--------+

[OUTDATED PACKAGES]
+----------------------------+---------+---------+------------+
| Package                    | Current | Latest  | Update Type|
+----------------------------+---------+---------+------------+
| express                    | 4.17.1  | 4.18.2  | minor      |
+----------------------------+---------+---------+------------+

SEVERITY SUMMARY:
  CRITICAL: 1
  HIGH: 0
  MEDIUM: 2
  LOW: 1
============================================================
```

### JSON Output

```json
{
  "vulnerabilities": [...],
  "outdated": [...],
  "license_issues": [...],
  "unused": [...],
  "scanned_files": [...],
  "scanned_count": 5,
  "error_count": 0,
  "scan_duration": 2.45,
  "summary": {
    "total_vulnerabilities": 4,
    "severity_breakdown": {
      "critical": 1,
      "high": 0,
      "medium": 2,
      "low": 1
    },
    "total_outdated": 3,
    "total_license_issues": 1,
    "total_unused": 2
  }
}
```

## CI/CD Integration

### GitHub Actions

Generate a workflow file:

```bash
depaudit generate-cicd github
```

This creates `.github/workflows/depaudit.yml` with:
- Scheduled scans (weekly by default)
- Scan on push to main
- Scan on PR creation
- Results uploaded as artifacts
- Comment on PR with summary

### GitLab CI

Generate a `.gitlab-ci.yml` section:

```bash
depaudit generate-cicd gitlab
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `DEPAUDIT_API_KEY` | API key for premium vulnerability databases |
| `DEPAUDIT_CACHE_DIR` | Custom cache directory |
| `DEPAUDIT_CONFIG_FILE` | Path to configuration file |
| `HTTP_PROXY` | HTTP proxy for API requests |
| `HTTPS_PROXY` | HTTPS proxy for API requests |

## Exit Codes

| Code | Description |
|------|-------------|
| 0 | No issues found or scan completed successfully |
| 1 | Issues found (configurable via `cicd.fail_on`) |
| 2 | Error during scan |

## Development

### Setup

```bash
git clone https://github.com/depaudit/depaudit-cli
cd depaudit-cli
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest tests/ -v --cov=depaudit
```

### Linting

```bash
black depaudit tests
ruff check depaudit tests
mypy depaudit
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) for details.