# pvtr

[![OSPS Baseline](https://github.com/privateerproj/pvtr/actions/workflows/osps-security-assessment.yaml/badge.svg)](https://github.com/privateerproj/pvtr/actions/workflows/osps-security-assessment.yaml)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15145/baseline)](https://www.bestpractices.dev/projects/15145/baseline-1)

**pvtr** is a validation framework that simplifies infrastructure testing and compliance validation. Built with infrastructure engineers in mind, pvtr helps accelerate security and compliance validation of any software asset.

## Key Features

- **Community-Driven Plugins**: Plugins are crafted and maintained collaboratively by the community or privately within your organization
- **Comprehensive Resource Validation**: Validate diverse resources in a single execution, regardless of how many resources or validations you need to queue
- **Consistent Machine-Readable Output**: Standardized output simplifies automation and integration
- **Plugin Generation**: Generate plugin scaffolding from [Gemara](https://gemara.openssf.org) Layer 2 schema catalogs with the push of a button

## Quick Start

**For detailed ecosystem documentation, visit [privateerproj.com](https://privateerproj.com)**

### Step 1: Star this Repo

Click the star at the top right of this page so that you can find it easily the next time you sign in to GitHub.

### Step 2: Choose Your Installation Method

#### Option 1: Install via Homebrew

```bash
brew install privateerproj/tap/pvtr
```

#### Option 2: Install via Script

```bash
/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/privateerproj/pvtr/main/install.sh)"
```

Installs the latest release to `~/.privateer/bin`, verifying its checksum before
installing. Pass flags after `--`:

```bash
/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/privateerproj/pvtr/main/install.sh)" -- -p /usr/local/bin -y
```

| Flag | Effect |
| --- | --- |
| `-p <dir>` | Install to `<dir>` instead of `~/.privateer/bin` |
| `-v <version>` | Install a specific release, e.g. `v0.22.0`, instead of the latest |
| `-y` | Add the install directory to `PATH` without prompting |
| `-h` | Print usage and exit |

`PVTR_VERSION` is equivalent to `-v`; the flag wins if both are set. Pin a
version to keep CI reproducible:

```bash
PVTR_VERSION=v0.22.0 /bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/privateerproj/pvtr/main/install.sh)" -- -p /usr/local/bin -y
```

Without `-y` the script asks before editing your shell config, and prints the
`PATH` line for you to add yourself if you decline or it is run unattended.
Installing to a directory you do not own (such as `/usr/local/bin`) requires
`sudo`.

#### Option 3: Download from Releases

Download the latest release from [GitHub Releases](https://github.com/privateerproj/pvtr/releases).

#### Option 4: Build from Source

```bash
git clone https://github.com/privateerproj/pvtr.git
cd pvtr
go mod tidy
make build
```

### Step 3: Choose Your Plugins

We do not currently maintain an authoritative list of community plugins, but a good place to start would be the OpenSSF's [plugin](https://github.com/revanite-io/pvtr-github-repo) for scanning GitHub repos against the _Open Source Project Security Baseline_.

### Step 4: Install & Verify Your Plugins

Plugin installation is currently left to the user. The default location for plugin binaries is `$HOME/.privateer/bin`. You may specify a different location at runtime via `--binaries-path` if you install your plugins elsewhere.

To review the plugins you have installed, run `pvtr list -a`.

## Contributing

We welcome contributions! See our [Contributing Guidelines](https://github.com/privateerproj/pvtr?tab=contributing-ov-file) for details.

All contributions are covered by the [Apache 2 License](https://github.com/privateerproj/pvtr?tab=Apache-2.0-1-ov-file) at the time the pull request is opened, and all community interactions are governed by our [Code of Conduct](https://github.com/privateerproj/pvtr?tab=coc-ov-file).

### Local Development Prerequisites

- **Go 1.25.1 or later** - Required for building pvtr and running tests
- **Make** - For using the Makefile build targets

### Testing

Run all tests:

```bash
make test
```

Run tests with coverage:

```bash
make testcov
```

### Available Make Targets

- `make binary` - Build the binary
- `make test` - Run tests and vet checks
- `make testcov` - Run tests with coverage report
- `make tidy` - Clean up go.mod dependencies
- `make release` - Build release binaries for all platforms
- `make build` - Alias for `tidy test binary`

### Project Structure

```bash
privateer/
├── cmd/              # CLI commands (run, list, generate-plugin, etc.)
├── test/             # Test data and fixtures
├── build/            # Build scripts and CI configurations
├── main.go           # Application entry point
└── go.mod            # Go module dependencies
```

## Security

Please do not open public issues for vulnerabilities or security questions. Report them privately through [GitHub private vulnerability reporting](https://github.com/privateerproj/pvtr/security/advisories/new), and see our [Security Policy](https://github.com/privateerproj/pvtr?tab=security-ov-file) for the full process.

See the [Security Policy](https://github.com/privateerproj/.github/blob/main/.github/SECURITY.md) for the project's EU Cyber Resilience Act (CRA) readiness statement.

## Helpful Links

- **[Privateer SDK](https://github.com/privateerproj/privateer-sdk)** - SDK for developing pvtr plugins
- **[Privateer Documentation](https://privateerproj.com)** - Complete documentation site
- **[Example Plugin](https://github.com/privateerproj/raid-wireframe)** - Reference implementation