🛡️ Release Sentry

Inspect release artifacts before they become security incidents.

A defensive, local-first security scanner for software release packages.
Find exposed secrets, unsafe archives, sensitive files, broken static assets, dangerous permissions, and policy violations before you publish or deploy.

Get started · Explore the checks · Read the docs · Report a vulnerability

---

Created and maintained by Taher Amine ELHOUARI
Website · GitHub · Official repository

Why Release Sentry?

A release can build successfully and still expose credentials, contain internal files, ship broken assets, preserve unsafe permissions, or hide a dangerous archive structure. Release Sentry adds a focused security gate between “the build passed” and “publish it.”

Source code  →  Build artifact  →  Release Sentry  →  Publish / Deploy
                                      │
                                      └─ secrets, archive safety, hygiene,
                                         permissions, completeness and policy

It scans directories, ZIP archives, TAR files, TAR.GZ files, and TGZ files without executing or blindly extracting their contents.

Quick start

Release Sentry requires Python 3.11 or newer.

Install the latest release

Download the wheel from the latest GitHub release, then run:

python -m pip install release_sentry-1.0.1-py3-none-any.whl

Scan an artifact

release-sentry scan dist/release.zip

Scan a static website and fail on high-risk findings

release-sentry scan public/ --profile static-web --fail-on high

Create and validate a project policy

release-sentry init --profile static-web
release-sentry validate-policy .release-sentry.yml

What it detects

Security area	Release Sentry checks
Archive safety	Path traversal, absolute paths, unsafe links, special entries, collisions, archive bombs, encryption, and quota violations
Secrets	Private keys, provider tokens, credentials, JWT-like values, and bounded entropy candidates—without disclosing the secret
Release hygiene	Environment files, dumps, backups, caches, VCS metadata, debug output, and internal notes
Completeness	Required files, one-of requirements, non-empty assets, and profile-specific production expectations
Permissions	Executable, world-writable, setuid/setgid, and signature-to-extension mismatches
Static websites	Missing assets, case mismatches, escaping paths, development URLs, source maps, and .htaccess requirements
Release evidence	Terminal, JSON, Markdown, JUnit XML, SARIF 2.1.0, and SHA-256/SHA-512 manifests

Built-in profiles:

generic · static-web · python-package · node-package · documentation · container-build-context

Useful commands

Command	Purpose
release-sentry scan PATH	Scan a directory or supported archive
release-sentry init	Generate a starter policy
release-sentry validate-policy FILE	Validate a policy before using it
release-sentry manifest PATH	Generate a stable SHA-256 or SHA-512 manifest
release-sentry compare OLD NEW	Highlight security risks introduced by a new release
release-sentry rules	List built-in rules and explanations
release-sentry version	Show version and project ownership information
release-sentry about	Display project, creator, and official links

Example policy

schema_version: "1.0"
profile: static-web
failure_threshold: high

require_htaccess: true
forbid_source_maps: true

required_paths:
  - path: index.html
    non_empty: true

forbidden_paths:
  - "**/*.bak"
  - "**/.env*"

allowed_executables: []

suppressions:
  - rule_id: RS-FILE-005
    path: "docs/Thumbs.db"
    justification: "Legacy fixture reviewed by the release owner"
    owner: release-team
    expires: 2027-01-01

Generate a starter with release-sentry init --profile static-web. See the policy reference and the machine-readable policy schema for every option.

Reports and automation

Choose the output that fits your workflow:

release-sentry scan dist/release.zip --format json --output report.json
release-sentry scan dist/release.zip --format markdown --output report.md
release-sentry scan dist/release.zip --format junit --output report.xml
release-sentry scan dist/release.zip --format sarif --output report.sarif

For GitHub Actions:

- name: Inspect release artifact
  uses: MrTaherAmine/release-sentry@v1
  with:
    path: dist/release.zip
    policy: .release-sentry.yml
    fail-on: high
    format: sarif

See the GitHub Actions guide for complete least-privilege examples and SARIF upload guidance.

Exit codes

Code	Meaning
0	Scan completed; no finding met the failure threshold
1	Scan completed; at least one finding met or exceeded the threshold
2	Invalid arguments, policy, or configuration
3	Artifact unreadable, corrupted, or unsupported
4	Internal failure or cancellation

Private by design

Release Sentry is read-only, offline, and local-first. During a scan it does not:

• execute artifact content;
• blindly extract archives;
• upload files or send network requests;
• modify the artifact being inspected;
• collect analytics or emit telemetry.

Secret evidence is fingerprinted and redacted in every output format. Reads are bounded, symlinks are not followed, and untrusted names and report fields are sanitized.

Read the security model and threat model for the complete design and trust boundaries.

Important

Release Sentry is a defensive review aid. It does not guarantee that an artifact is secure, compliant, malware-free, or free of every possible secret. Binary semantic analysis, digital-signature verification, and recursive nested-archive scanning are outside v1.0.

Quality and security

Release Sentry v1.0.1 is validated with 100% measured test coverage across 1,074 statements and 348 branches, with the project quality gate set to 99.99%.

The release is also checked with Ruff, strict MyPy, Bandit, dependency auditing, package build verification, clean-environment installation, and a Release Sentry self-scan.

Documentation

Guide	Description
Architecture	Components, data flow, and design boundaries
Rule catalogue	Built-in rules, severity, and remediation guidance
Policy reference	Configuration and suppression reference
Output formats	Terminal, JSON, Markdown, JUnit, and SARIF outputs
GitHub Actions	CI integration and least-privilege examples
Creating rules	Contributor guide for new detections
Security policy	Supported versions and vulnerability reporting
Contributing	Development setup and contribution process

Contributing

Contributions, responsible testing, documentation improvements, and new defensive detection ideas are welcome. Please read CONTRIBUTING.md and the Code of Conduct before opening a pull request.

For security-sensitive reports, follow SECURITY.md instead of opening a public issue.

License and attribution

Release Sentry is released under the MIT License.

Created and maintained by Taher Amine ELHOUARI.
Copyright © 2026 Taher Amine ELHOUARI. All project attribution, official links, and provenance information must remain consistent with the license and repository history.

---

Secure the release before the release becomes the incident.

Website · GitHub profile · Releases · Issues