sentinel-scanner 1.0.10

AI-powered security hardening for Python & frontend developers

Sentinel - AI-Powered Security Hardening

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.

---

Features

• 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.

---

Quick Start

# 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 . --ai

For full documentation, visit Sentinel Docs.

---

Vulnerability Detection & Offline Remediations

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).

---

Distribution & Running

• 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.

---

GitHub Actions / CI/CD Workflows

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[...]

---

Project Documentation & Useful Guides

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.

---

License

This project is licensed under the GPLv3 license. See the LICENSE file for details.

---

Show your support

Give a star if this project helped you!

---

Community & Socials

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