An agentic business-logic security auditor that identifies risky code paths, validates findings, and produces actionable security reports.
- 1. Project Name & Tagline
- 2. Table of Contents
- 3. Project Overview
- 4. Quick Start
- 5. Usage
- 6. Configuration
- 7. Project Structure
- 8. Development
- 9. Deployment
- 10. FAQ
- 11. License
Modern application risk is often caused by business-logic flaws (IDOR, broken authorization logic, insecure workflow assumptions), not only syntax-level vulnerabilities. SentinelFlow is designed to audit repository behavior and report practical security findings.
- Repository ingestion and source filtering.
- Function-level static analysis for risky business-logic patterns.
- Agent-assisted vulnerability hunting workflow.
- Optional sandbox-style verification output in scan reports.
- Scan CRUD APIs for create, read, update, and delete operations.
- Local Streamlit dashboard for scan orchestration and review.
- Comprehensive test system with Unit, Integration, and Playwright E2E coverage.
- Security checks before pull request merge.
- Internal AppSec triage for backend repositories.
- Training or demonstration using intentionally vulnerable examples.
- Continuous validation in CI/CD pipelines.
- Frontend/UI: Streamlit dashboard.
- Backend/API: FastAPI.
- Worker/Async: Celery + Redis.
- Analysis: Python + Tree-sitter.
- Testing: Pytest, Vitest, Playwright.
- CI/CD: GitHub Actions.
- Operating systems: Windows, macOS, Linux.
- Python: 3.10+.
- Node.js: 20+ recommended.
- Tools: Git, pip, npm, optional Docker.
- Clone the project.
git clone https://github.com/Brian-code-123/Hunter.git
cd Hunter- Install Python dependencies.
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt- Install Node dependencies.
npm install
npx playwright install --with-deps chromium- Configure environment variables when needed.
cp .env.example .env # if you maintain an env template in your environment- Start services.
uvicorn sentinelflow.api.main:app --reload --port 8000
streamlit run sentinelflow/ui/dashboard.py- Visit endpoints.
- API docs: http://localhost:8000/docs
- Dashboard: http://localhost:8501
Start a sync scan:
curl -X POST http://localhost:8000/scan/sync \
-H "Content-Type: application/json" \
-d '{"repo_url":"./vulnerable-samples","branch":"main","include_extensions":[".py",".js"],"mode":"sync"}'# Python unit + integration
pytest -q tests/unit tests/integration
# Python Playwright E2E
pytest -q tests/e2e -m "e2e and browser"
# JavaScript unit + integration
npm run test:unit:js
npm run test:integration:js
# TypeScript Playwright E2E
npm run test:e2e:playwright- POST /scan: create async scan task.
- GET /scans: list stored scan records.
- GET /scan/{task_id}: read a scan by task id.
- PUT /scan/{task_id}: update scan label/notes.
- DELETE /scan/{task_id}: delete a scan record.
- Open the dashboard and set the API base URL.
- Start scan from sync or async mode.
- Use scan registry actions to load, read, update, and delete scan records.
- Main walkthrough: video.webm
- CI pipeline walkthrough: ci-pipeline-demo.mp4
- CRUD browser flow: playwright-crud-demo.mp4
- SENTINELFLOW_APP_NAME: display name.
- SENTINELFLOW_REDIS_URL: Redis endpoint.
- SENTINELFLOW_CELERY_BROKER_URL: worker broker URL.
- SENTINELFLOW_CELERY_RESULT_BACKEND: worker result backend URL.
- SENTINELFLOW_SANDBOX_ENABLED: enable or disable verification mode.
- SENTINELFLOW_RUNS_BASE_DIR: output directory for scan results.
- SENTINELFLOW_DASHBOARD_API_BASE: dashboard default API endpoint.
- SENTINELFLOW_DASHBOARD_DEFAULT_MODE: dashboard default mode (sync/async).
- Python runtime dependencies: requirements.txt
- JavaScript test dependencies: package.json
- Playwright behavior: playwright.config.ts
- Pytest behavior: pytest.ini
- CI workflow: .github/workflows/ci.yml
- Restrict file extensions in scan payload for faster runs.
- Disable sandbox in constrained CI environments.
- Adjust worker and Redis endpoints by deployment environment.
.
├── .github/workflows/ # CI/CD workflows
├── docs/ # Documentation and media references
├── scripts/ # Helper scripts
├── sentinelflow/ # Application package
│ ├── api/ # FastAPI app and routes
│ ├── core/ # Ingestion, analysis, pipeline, reporting
│ ├── ui/ # Streamlit dashboard
│ └── workers/ # Celery app and worker tasks
├── tests/ # Python tests (unit/integration/e2e)
├── tests-js/ # JS/TS tests (unit/integration/e2e)
├── vulnerable-samples/ # Intentionally vulnerable sample targets
├── web/ # Test helper client modules
├── docker-compose.yml # Local stack definition
├── Dockerfile.api # API/worker image
├── Dockerfile.dashboard # Dashboard image
└── README.md # Project documentation
- Use clear naming and small, focused modules.
- Keep behavior testable and deterministic.
- Follow PEP 8 for Python and keep TypeScript strict.
- Use concise imperative messages.
- Recommended prefixes: feat, fix, test, docs, chore.
- main: stable branch.
- dev: integration branch (optional).
- feature/*: short-lived feature branches.
- Deploy preview from pull requests.
- Validate /health and /docs endpoints before merge.
- Deploy API and dashboard with environment-specific secrets.
- Keep CI artifact retention enabled for debugging failures.
docker compose up --build- Place FastAPI behind Nginx or equivalent reverse proxy.
- Route API and dashboard traffic according to your environment topology.
Ensure Python Playwright browsers are installed with:
python -m playwright install --with-deps chromiumConfirm the dashboard API base URL points to a running FastAPI instance.
Verify Redis/Celery worker is running and broker/backend URLs are correct.
Ensure test output paths are preserved and upload-artifact steps run with if: always().
MIT