Sentinel is a developer-first CLI tool that finds security vulnerabilities in projects (supporting Python, JavaScript/TypeScript, HTML, CSS, and dependencies) and provides AI-powered fixes - all in an interactive terminal dashboard.
- SAST - detects SQLi, XSS, command injection, hardcoded secrets, insecure crypto, and frontend/HTML vulnerabilities.
- SCA - checks dependencies against OSV.dev and NVD.
- DAST - optionally tests running web apps.
- AI enrichment (Mistral) - re-evaluates severity, explains attack scenarios, suggests fixes.
- Interactive TUI - no more grepping JSON logs.
- Auto-fix - applies safe remediations.
- CI/CD ready - GitHub Action, Docker, PyPI.
# Install
pip install sentinel-scanner
# Scan
sentinel scan .
# With AI (get a free key from Mistral AI)
export MISTRAL_API_KEY=your-key
sentinel scan . --aiFor full documentation, visit Sentinel Docs.
Sentinel works fully out-of-the-box in offline mode. If no AI API key (Mistral) or local Ollama instance is configured, Sentinel still maps findings directly to established security remediation protocols based on industry standards:
| Vulnerability Type | CWE | Description | Standard Remediation Protocol |
|---|---|---|---|
| SQL Injection (SQLi) | CWE-89 | Concatenating untrusted user inputs directly into SQL query strings. | Use parameterized queries (prepared statements) e.g., execute("SELECT * FROM users WHERE id = ?", (user_id,)) or ORMs. Never format/interpolate SQL strings. |
| Cross-Site Scripting (XSS) | CWE-79 | Rendering untrusted user inputs in HTML templates or outputs without escaping. | Remove dangerous raw render calls (` |
| Command Injection | CWE-78 | Executing OS commands via subprocess calls with dynamic strings and shell=True. |
Disable shell execution (shell=False). Pass command strings as sequences of args e.g., subprocess.run(["ls", "-la"]) to prevent shell parser manipulation. |
| Hardcoded Secrets | CWE-798 | Storing passwords, API tokens, keys, and private credentials directly inside source code. | Move all configuration and credentials to environment variables loaded via .env (e.g., os.getenv("DB_PASS")). Always add .env to .gitignore. |
| Insecure Cryptography | CWE-326 | Utilizing weak or deprecated hashing algorithms (like MD5 or SHA-1) and weak ciphers. | Upgrade cryptosystems to strong alternatives (e.g., hashlib.sha256 or hashlib.sha3_256 for hashes, and AES-GCM for symmetric encryption). |
| Frontend/HTML Vulnerabilities | CWE-79 | Frontend-specific security risk such as unsafe HTML rendering, reverse tabnabbing, un-sandboxed iframe, or inline scripts/events. | Avoid dangerouslySetInnerHTML/v-html/innerHTML without DOMPurify sanitization. Use rel="noopener noreferrer" for target="_blank". Add sandbox to iframe tags. Avoid javascript: URIs, inline scripts, and inline event handlers. |
| Outdated Dependencies | CWE-1395 | Importing packages containing known CVEs published in OSV.dev and NVD databases. | Pin safe dependencies in lockfiles (poetry.lock, uv.lock, package-lock.json) and run package upgrade managers (e.g. pip install --upgrade). |
- PyPI:
pip install sentinel-scanner - Docker: Run Sentinel in a containerized environment (details in Docker README):
docker run --rm -v $(pwd):/app ghcr.io/ronaldgosso/sentinel:latest scan .
- GitHub Action: Integrate into your workflows using
uses: ronaldgosso/sentinel-action@v1.
The repository uses automated GitHub Actions workflows to maintain code quality, build Docker images, publish PyPI releases, and host the documentation website:
| Workflow | File | Trigger | Description |
|---|---|---|---|
| Continuous Integration (CI) | ci.yml | Push/PR to main |
Runs tests, Ruff (linting), and Mypy (type checking) to ensure code meets quality standards before merg[...] |
| Publish to PyPI | pypi-publish.yml | Push tag v*.*.* |
Runs quality checks first. If successful, builds wheels and publishes the distribution packages[...] |
| Build & Publish Docker | docker-build.yml | Push to main, tags v*, or PyPI success |
Automates building the optimized multi-stage Python wheel Docke[...] |
| Deploy Docs | docs.yml | Push to main |
Deploys static files from the website/ folder directly to GitHub Pages at [https://ronaldgosso.github.io/sentinel](h[...] |
Check out these documents to learn more about developing, building, and contributing to Sentinel:
- Docker Guide - Details on running Sentinel via Docker, passing environment variables (like API keys), and exporting reports.
- Contributing Guidelines - Guide on repository setup, adding custom SAST/AST detectors, running tests, and the Pull Request/release process.
- Product Roadmap - Overview of features planned for future releases (v1.1, v1.2, and v2.0).
- Security Policy - Instructions on how to report security vulnerabilities privately.
- Code of Conduct - Standards of behavior to ensure a welcoming community.
This project is licensed under the GPLv3 license. See the LICENSE file for details.
Give a star if this project helped you!
Spread the word and share your journey with Sentinel using these engaging hashtags across GitHub, Twitter/X, and LinkedIn:
- Global Tech & AppSec:
#Cybersecurity#AppSec#DevSecOps#PythonSecurity#AISecurity#OpenSource#StaticAnalysis - Tanzania & Africa Tech:
#TanzaniaTech#SiliconDar#TechInTanzania#TanzaniaDevelopers#CodingInTanzania#AfricaTech