Metadata-Version: 2.4
Name: speculynx
Version: 0.1.2
Summary: Local-first OpenAPI 3.0/3.1 security audit CLI
Author: Sami-BUTRT
License-Expression: MIT
Project-URL: Homepage, https://github.com/Sami-BUTRT/speculynx-cli
Project-URL: Repository, https://github.com/Sami-BUTRT/speculynx-cli
Project-URL: Issues, https://github.com/Sami-BUTRT/speculynx-cli/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1,>=0.12
Requires-Dist: PyYAML<7,>=6
Requires-Dist: httpx<1,>=0.27
Requires-Dist: fpdf2<3,>=2.7
Requires-Dist: keyring<26,>=25
Dynamic: license-file

# Speculynx CLI

Speculynx is a local-first Python/Typer CLI for auditing OpenAPI 3.0.x and
3.1.x files for API security risks. Swagger 2.0, GraphQL, gRPC, and SOAP are
outside the MVP scope.

OpenAPI files are analyzed locally. Speculynx does not send customer OpenAPI
documents to the backend. Free scans work without a license and without network
access.

## Install

From a local checkout:

```powershell
python -m pip install -e .
```

After a package build, install the wheel locally:

```powershell
python -m pip install dist\speculynx-0.1.2-py3-none-any.whl
```

## Commands

```powershell
speculynx --help
speculynx scan --file path\to\openapi.yaml
speculynx login
speculynx info
speculynx logout
```

`login` verifies a Pro license key with:

```text
POST /v1/verify
Authorization: Bearer <license_key>
```

The key is stored with the operating-system credential store through `keyring`.
Legacy `~/.speculynx.json` files are ignored.

## Free Scan

```powershell
speculynx scan --file path\to\openapi.yaml
```

Free rules include:

- `KEY-EXP-01`: keys or tokens exposed in query parameters.
- `HTTP-001`: insecure `http://` server URLs.
- `AUTH-001`: missing documented authentication.
- `KEY-EXP-02`: missing documented key/token expiration.

## Pro Scan

With a valid Pro license, `scan` also runs heuristic checks for patterns such as
BOLA, BFLA, sensitive data exposure, likely secrets in examples, SSRF inputs,
missing rate-limit documentation, and unclear API inventory/versioning.

Pro findings are static analysis signals, not proof of runtime vulnerabilities.
They should be manually verified against backend authorization, gateway, and
infrastructure controls.

## PDF Export

PDF export is Pro-only:

```powershell
speculynx scan --file path\to\openapi.yaml --export report.pdf
```

In Free mode the export is refused.

## Live Scan / DAST

`scan-live` is Pro-only and can send real HTTP requests to a target API. It is
safe-by-default:

- only `GET` requests are sent by default;
- `POST`, `PUT`, `PATCH`, and `DELETE` require `--allow-unsafe-methods`;
- `--yes` does not unlock unsafe methods by itself;
- `--dry-run` prints planned requests without sending HTTP traffic;
- `--insecure` must be explicitly provided to disable TLS verification.

Examples:

```powershell
speculynx scan-live --file openapi.yaml --target https://api.example.com --dry-run
speculynx scan-live --file openapi.yaml --target https://api.example.com --yes
speculynx scan-live --file openapi.yaml --target https://api.example.com --yes --allow-unsafe-methods
```

Only run `scan-live` against systems you own or are explicitly authorized to
test.

## Development

```powershell
python -m unittest discover -s tests -v
python -m build
```
