Metadata-Version: 2.4
Name: pentesterra-devguard
Version: 1.4.2
Summary: Pentesterra DevGuard — pre-push security audit CLI agent
License: Proprietary
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0

# Pentesterra DevGuard

Pre-push security audit CLI agent for developers.

## Installation

```bash
pip install pentesterra-devguard
```

Or download the pre-built archive:

```bash
curl -LO https://www.pentesterra.com/devguard.tar.gz
pip install devguard.tar.gz
```

## Quick Start

```bash
# 1. Initialize with your API key (get it from Pentesterra dashboard)
pentesterra-devguard init

# 2. Run a scan in your project directory
cd /path/to/your/project
pentesterra-devguard scan

# 3. View results
pentesterra-devguard results <scan_id>
```

## Commands

| Command | Description |
|---------|-------------|
| `init` | Configure API URL and DevGuard API key |
| `scan [path]` | Collect project data and submit a security scan |
| `status <scan_id>` | Check scan status |
| `results <scan_id>` | View detailed scan results |
| `projects` | List registered projects |
| `scans` | List recent scans |
| `quota` | View quota usage |
| `update` | Download and install the latest CLI version |

### Auto-update

The CLI checks for updates on every scan (at most once per 24 hours) and shows a notice when a newer version is available:

```
ℹ  DevGuard v1.X.X is available — run: pentesterra-devguard update
```

Updates are downloaded from `api.pentesterra.com`, SHA256-verified before installation, and applied via pip.

## VS Code / Cursor / Windsurf Extension

DevGuard is also available as an IDE extension.

### Option A — VS Code Marketplace (recommended, auto-updates)

```bash
code --install-extension pentesterra.pentesterra-devguard
```

Marketplace installs update automatically through VS Code's built-in update mechanism.

### Option B — Download .vsix from our site (also auto-updates)

```bash
# VS Code
code --install-extension devguard.vsix

# Cursor
cursor --install-extension devguard.vsix

# Windsurf
windsurf --install-extension devguard.vsix
```

Download: https://www.pentesterra.com/devguard.vsix

When installed from our site, the extension checks for updates automatically (once per 24 hours)
and offers a one-click update with SHA256 integrity verification.

### Zero-setup

The extension **automatically downloads and installs the CLI on first use** — no separate pip install required.
On subsequent launches the extension verifies the CLI is present; if not found, it prompts to install.

The extension uses the CLI as a subprocess for all analysis — same Python core, same detection quality.

## Scan Options

```bash
pentesterra-devguard scan . --project my-app --mode deep --no-wait
```

- `--project, -p` — Project alias (default: directory name)
- `--mode, -m` — `standard` or `deep`
- `--wait/--no-wait` — Wait for analysis to complete (default: wait)
- `--timeout` — Max seconds to wait (default: 120)
- `--dry-run` — Show payload without uploading

## JSON Output

All commands support `--json` for machine-readable output (used by IDE extensions):

```bash
pentesterra-devguard --json scan .
pentesterra-devguard --json results <scan_id>
pentesterra-devguard --json quota
```

Output format:
```json
{"ok": true, "data": {...}}
{"ok": false, "error": "message", "code": "NOT_CONFIGURED"}
```

## What Gets Collected

**Privacy-first**: No source code is ever transmitted.

- **Dependencies** — Package names and versions from lockfiles (npm, pip, go, ruby, php, rust)
- **Secrets metadata** — Type, file path, line number, masked value (actual secrets are NOT sent)
- **Misconfigurations** — Known config issues (Dockerfile, .env, docker-compose)
- **Project metadata** — Tech stack hints, file count

## Supported Lockfiles

- `package-lock.json`, `yarn.lock` (Node.js)
- `requirements.txt`, `Pipfile.lock`, `poetry.lock` (Python)
- `go.sum` (Go)
- `Gemfile.lock` (Ruby)
- `composer.lock` (PHP)
- `Cargo.lock` (Rust)

---

## For Developers: Publishing to PyPI

### Prerequisites

```bash
# Install build tools
pip install build twine
```

### Setup (one-time)

Create `publish_config.ini`:

```ini
[pypi]
api_token = pypi-your-token-here
```

Get your token from: https://pypi.org/manage/account/token/

**Note:** `publish_config.ini` is already in `.gitignore` and won't be committed.

### Quick Publish

```bash
# 1. Update version in pentesterra_devguard/__init__.py
# 2. Publish (PyPI + website artifacts)
python build_release_assets.py
```

This will:
- Build wheel + source distribution → **Publish to PyPI**
- Build devguard.tar.gz + devguard.vsix for the website
- Update API configs with SHA256 checksums

To skip PyPI publication:
```bash
python build_release_assets.py --skip-pypi
```

### Automated Release Script

```bash
./release.sh 1.3.56
```

The script will:
1. Update version in `__init__.py`
2. Show git status for review
3. Ask for confirmation
4. Build and publish to PyPI
5. Verify publication

### Publish Options

```bash
# Full release (PyPI + website artifacts) — DEFAULT
python build_release_assets.py

# Only website artifacts (no PyPI)
python build_release_assets.py --skip-pypi

# Only PyPI (skip tar.gz/vsix)
python build_release_assets.py --skip-tar --skip-vsix --skip-config
```

### Build core

```
python -m build
pip install ./dist/pentesterra_devguard-1.3.95.tar.gz 
```

### Documentation

- `PYPI_PUBLISH.md` — Detailed publishing guide
- `RELEASE_CHECKLIST.md` — Step-by-step release checklist
- `QUICK_PUBLISH.txt` — Quick reference card
