Vintar
Vintar is a Python tool for running authorized web security regression checks in CI. It runs reviewed cases against a configured target and reports the batch result as JSON and a process exit code.
Supported Scope
Vintar supports Boolean-based SQL injection regression checks for
GET query parameters. OpenAPI 3.0 and 3.1 discovery, draft review, and case
materialization run offline. The workflow is
discover → review-draft → materialize-case → verify. Reviewers explicitly
select the string-quoted or numeric probe preset when using presets.
Verification runs against an authorized, configured target.
Deferred to v0.2 and later are confirmed VULNERABLE verdicts and CLI integration
of 12-probe confirmation, time-based, error-based, and UNION-based SQL injection
checks, POST form and JSON body injection, cookie and header injection, and
authenticated workflows.
Install from PyPI
Use Python 3.13 or later. With uv, install Vintar as a CLI tool.
uv tool install vintar
Alternatively, install it in an active virtual environment with pip.
pip install vintar
Install from Source
For development, clone the repository and install from the lockfile.
git clone https://github.com/natori-hrj/vintar.git
cd vintar
uv sync --locked
The examples below use uv run --locked vintar from a source checkout. With an
installed CLI, use vintar in its place.
Run Your First Regression Batch
Create a TOML Case
Save this example as security/cases/a-case.toml. It expects a test fixture with an /ok endpoint and a category query parameter. Adapt the path, parameter, and reviewed probe values to your authorized fixture. --cases accepts one TOML file or a directory of TOML files. Directory discovery is nonrecursive.
version = 1
id = "a-case"
type = "sqli.boolean"
expected_verdict = "not_detected"
[target]
url = "http://placeholder.invalid:8000/ok"
allowed_origin = "http://placeholder.invalid:8000"
[[target.params]]
name = "category"
value = "Pets"
[injection]
location = "query"
name = "category"
occurrence = 0
mode = "append"
[probes]
true_payload = "true-probe"
false_payload = "false-probe"
[limits]
max_requests = 6
requests_per_second = 10.0
timeout_seconds = 5.0
Configure the Authorized Target
Run verification only against systems you own or have explicit permission to test. --authorized is your attestation. Set both VINTAR_TARGET_ORIGIN and VINTAR_ALLOWED_ORIGIN to the authorized service's exact origin in the trusted CI environment. Vintar replaces the case's placeholder origin with the runtime target and preserves the case path. Keep credentials and secrets out of origins and case files.
Run vintar verify
Replace https://staging.example.com with your authorized fixture origin.
VINTAR_TARGET_ORIGIN=https://staging.example.com \
VINTAR_ALLOWED_ORIGIN=https://staging.example.com \
uv run --locked vintar verify \
--cases security/cases/a-case.toml --max-requests 6 --authorized
Exit Codes and JSON Reports
| Case outcome or batch condition | verify exit code |
CI meaning |
|---|---|---|
NOT_DETECTED matches the reviewed expectation for every case in a complete batch |
0 |
PASS. No Boolean differential was detected under the tested probes and conditions. This does not prove SQL injection is absent. |
INCONCLUSIVE with reason boolean_candidate |
3 |
BLOCK / Review required. A SQLi-like Boolean response differential was observed. This is a candidate signal and requires independent evidence before anyone can call it a confirmed vulnerability. |
Other INCONCLUSIVE reasons or an incomplete batch |
3 |
BLOCK / Investigation required. Verification was insufficient. Check the budget, rate limits, transport or HTTP status, and response stability. |
FAIL |
1 |
FAIL. A NOT_DETECTED result did not match the reviewed expectation. |
ERROR |
2 |
ERROR. Invalid input, configuration, execution, or output prevented a usable result. |
| Interrupted | 130 |
Interrupted. A usable report may be absent. |
These are batch exit codes. A failed case takes precedence over inconclusive outcomes and an incomplete batch. An inconclusive case never passes, even when its verdict matches the expectation.
verify emits one schema v1 JSON report on stdout for results 0, 1, and 3. Diagnostics go to stderr. Use --pretty for indentation. An error or interruption can leave stdout empty or incomplete.
This excerpt shows the summary fields of a passing report.
{
"schema_version": 1,
"report_type": "regression_batch",
"status": "pass",
"exit_code": 0,
"complete": true,
"requests_used": 6
}
Integrate with GitHub Actions
- PR loopback checks. The PR workflow runs lint, architecture checks, and pytest before loopback E2E. The E2E uses a local fixture and verifies the batch exit and report contracts.
- Authorized staging verification. The staging workflow is manually dispatched from
mainusing thesecurity-testingenvironment. Configure the trusted origins and add reviewed cases undersecurity/cases/. - Report validation and artifacts. The staging workflow captures the CLI exit code, validates the report against it, and uploads the report only after validation. An absent or invalid report becomes workflow error
2, including when the CLI was interrupted. Restrict artifact access because case IDs and response metadata can be sensitive.
See the CI integration guide for setup and operational details.
Scope, Request Budgets, and Rate Limits
Verification scope is the origin, which consists of scheme, host, and port. Redirects are disabled. The batch preflights its cases against --max-requests before sending traffic and shares one request budget and rate limiter across the batch. --rps, --timeout, and --max-response-size set trusted caps. Case settings can tighten the applicable limits.
Apply network egress controls in sensitive environments. Origin validation leaves DNS-resolved IPs and individual URL paths outside its enforcement.
Discover Inputs for Review
Use vintar discover to inventory a single local OpenAPI 3.0 or 3.1 spec in JSON or YAML. The report lists operations, declared inputs, held and ignored items, and source pointers. Discovery performs no HTTP requests. It produces review data that is separate from regression case files.
Run discovery with your local openapi.json to find stable input IDs. To reproduce this example, copy tests/fixtures/discovery/openapi30.json to openapi.json. Commit review.toml with the IDs a reviewer approved. Omit --selection to inventory inputs before review.
version = 1
approved = ["input-24a9c3cf0c3d01709121ac0d09079903"]
uv run --locked vintar discover \
--spec openapi.json --selection review.toml --output inventory.json
inventory.json contains the versioned report. Stdout contains one JSON summary and stderr carries diagnostics. Exit codes are 0 for success, 2 for invalid input or output, and 130 for interruption. Choose an output path separate from the spec and selection.
{
"schema_version": 1,
"report_type": "discovery_summary",
"operations": 3,
"selected": 1
}
Export Review Drafts
After reviewing review.toml, export one draft per approved input. Run from a directory that contains the spec so the draft can record a relative source path.
uv run --locked vintar discover \
--spec openapi.json --selection review.toml --drafts-dir drafts
{
"report_type": "discovery_draft_summary",
"schema_version": 1,
"drafts": ["case-24a9c3cf0c3d01709121ac0d09079903.draft.toml"]
}
Drafts record declared inputs and decisions still needed. Keep them outside your verification case directory. vintar verify rejects them and requires reviewed Schema v1 cases. Reruns leave identical drafts in place. If a file conflicts, review it or select a new destination.
Draft export requires a filesystem that supports hard links, such as ext4, APFS, or NTFS. Choose another --drafts-dir if your current destination is on exFAT or FAT32.
Record Draft Review Decisions
Save the reviewer’s decisions in answers.json. Each declared query parameter needs an explicit value, a local pointer to a declared example, default, or single-value enum, or {"omit": true} for an optional parameter. Null and compound values are rejected. Explicit pointers may include value_sha256 to detect changed values during re-review. The digest uses compact ASCII-escaped JSON with sorted keys. Choose the expected verdict explicitly.
{
"version": 1,
"expected_verdict": "not_detected",
"parameters": {"q": {"value": "fixture-baseline"}}
}
uv run --locked vintar review-draft \
--spec openapi.json --draft drafts/case-24a9c3cf0c3d01709121ac0d09079903.draft.toml \
--answers answers.json --output review.json
{
"schema_version": 1,
"report_type": "discovery_draft_review_summary"
}
The offline report records evidence, omission decisions, and value digests. It contains no raw baseline values. vintar verify requires a separately reviewed Schema v1 TOML case. Reruns preserve identical output and refuse to replace conflicting files. The output filesystem must support hard links.
Materialize a Reviewed Case
Create an explicit target config for the reviewed input. The target URL is the route that verification will call; it may include a proxy prefix or fixture route and is not inferred from the OpenAPI path. Origins, injection behavior, limits, security expectations, and probe selection are never guessed. Headers, cookies, and credentials are not accepted in this config.
config_version = 1
input_id = "input-24a9c3cf0c3d01709121ac0d09079903"
[target]
url = "http://cli-fixture.invalid/fixture-route"
allowed_origin = "http://cli-fixture.invalid"
[injection]
location = "query"
name = "q"
occurrence = 0
mode = "append"
[probes]
selection = "explicit"
true_payload = "true-probe"
false_payload = "false-probe"
[limits]
max_requests = 6
requests_per_second = 10.0
timeout_seconds = 5.0
uv run --locked vintar materialize-case \
--spec openapi.json --draft drafts/case-24a9c3cf0c3d01709121ac0d09079903.draft.toml \
--answers answers.json --review review.json --config case-config.toml \
--output security/cases/case-24a9c3cf0c3d01709121ac0d09079903.toml
{
"case_id": "case-24a9c3cf0c3d01709121ac0d09079903",
"confirmation": "not configured",
"max_requests": 6,
"report_type": "regression_case_materialization_summary",
"schema_version": 1
}
Materialization is offline. It regenerates the draft and review decisions from the current spec and answers, verifies the supplied review report including value SHA-256 digests, and validates the generated TOML with the Schema v1 loader. The case ID comes from the regenerated draft. Optional parameters answered with {"omit": true} are absent from target.params; an explicit empty string remains value = "". Strings are preserved exactly, while booleans, integers, and finite floats use compact canonical JSON scalar text (true, 17, or 1.25).
The generated case contains the reviewed raw parameter values and explicit probe payloads, so treat it as sensitive review material. Rerunning with byte-identical content is a no-op. Existing conflicting output is preserved, and publishing requires a hard-link-capable filesystem.
Instead of supplying explicit payloads, a reviewer may select one reviewed Boolean probe preset:
[probes]
selection = "preset"
preset = "string-quoted"
The supported presets are string-quoted and numeric. Materialization expands
the selected initial pair and its reviewed second pair plus baseline-preserving
third predicate into the Schema v1 case; preset cases therefore use
max_requests = 18. The reviewer must explicitly choose a
preset for the downstream SQL context. An OpenAPI integer type alone cannot
establish that context.
With selection = "explicit", the reviewer may either omit confirmation and use
max_requests = 6, or explicitly supply all three confirmation fields and use
max_requests = 18. Explicit payloads are never matched to or completed from a
preset.
Other CLI Commands
vintar --helplists commands, andvintar versionprints the current project version.vintar http sendinspects a GET or POST response and prints text. It accepts--body,--header,--cookie, repeatable--param, and--timeout. The response body limit for this command is 1 MiB.vintar sqli verifyruns a single bounded Boolean check and exits0whenever it emits a report, including aninconclusiveverdict. Useverifyfor a batch gate that distinguishes PASS, FAIL, and INCONCLUSIVE.
For the same authorized test fixture, a single-check invocation looks like this.
uv run --locked vintar sqli verify \
--url https://staging.example.com/ok --allow-origin https://staging.example.com \
--param category=Pets --inject-param category --append \
--true-payload true-probe --false-payload false-probe \
--authorized
{
"schema_version": 1,
"check_type": "sqli_boolean",
"verdict": "not_detected",
"reason_code": "no_boolean_difference",
"request_count": 6
}
Current Limitations
- Non-SQL middleware can mimic a Boolean response differential. The
waf200_mimicfixture demonstrates a false candidate. Vintar does not claim zero false candidates across environments. - Matched live loopback evaluation covers ephemeral SQLite twins using the
corresponding
string-quotedandnumericpresets. The observed candidate counts were TP=2, TN=2, FP=0, FN=0 for those fixtures. PostgreSQL and MySQL integration tests are opt-in and do not run in default CI. - Schema v1 uses placeholder origins. Verification binds the case to the trusted runtime origin.
- The batch engine has per-request timeouts. The staging workflow supplies the job-level timeout.
- Schema validation checks the report. Case definitions still require trusted review.
Development and Golden Tests
uv run pytest
uv run ruff check
uv run ruff format --check
uv run lint-imports
uv run python scripts/check_architecture.py
The CLI golden tests use deterministic fixtures. After an intentional output change, run uv run python scripts/update_cli_goldens.py --write and review the resulting diff. The README examples are checked against the same goldens by pytest.
On Linux x86-64, run uv run python scripts/scan_git_history.py from a full Git checkout to scan committed secrets. The first run downloads the pinned Gitleaks archive from GitHub. Later scans and pytest reuse the cached archive and verify its SHA-256 before each use. CI warms the same cache in the scan step before pytest. A download or verification failure fails the scan and its tests.
See the security policy to report a vulnerability privately.
License
Vintar is licensed under the Apache License, Version 2.0.
Metadata
Release files for vintar 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vintar-0.2.1.tar.gz | 116.9 kB | With provenance | Details for vintar-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vintar-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for vintar-0.2.1-py3-none-any.whl |
Total release size: 258.2 kB
Release files / vintar-0.2.1.tar.gz
| Download URL | vintar-0.2.1.tar.gz |
|---|---|
| Size | 116.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
00c85f5d797fdd3c9070204e63875f6a0f212c070e404e6e65571f72e8f5d788
|
|
BLAKE2b-256 checksum How to use checksums |
7689e5d877fc5ab24a6d07598a6c8fe43619d671c9864bdac8886d87a9af6801
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / vintar-0.2.1-py3-none-any.whl
| Download URL | vintar-0.2.1-py3-none-any.whl |
|---|---|
| Size | 141.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bcad03ed4c6910ccf13302536270836cd1230afd518b186013fec3b5f6472517
|
|
BLAKE2b-256 checksum How to use checksums |
db1921b4e677b59b0f03394b543985ee40f063229df7422690a1dfb73d683f35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for vintar 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vintar-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.