# Sentinel

**CLI-first DevSecOps audit toolkit** by Cephalon Labs.

Sentinel scans local repository checkouts for security issues across CI/CD pipelines, source code management hygiene, hardcoded secrets, and vulnerable dependencies. It produces SOC 2, CIS Benchmark, OWASP CI/CD Top 10, and ISO 27001-mapped findings in your choice of JSON, Markdown, HTML, or PDF output.

> Sentinel is an offline scanner. It works on code already on your machine — no GitLab API credentials required.

---

## Quick Start

```bash
# 1. Install system dependencies (Arch Linux — run once with sudo)
sudo bash scripts/install-system-deps.sh

# 2. Create virtualenv and install Sentinel
bash scripts/setup-dev.sh
source .venv/bin/activate

# 3. Scan a local repository
sentinel audit /path/to/your/repo --format json

# 4. Generate a full PDF report
sentinel audit /path/to/your/repo --format pdf --format json

# 5. Run only the CI/CD module
sentinel audit /path/to/your/repo --module cicd

# 6. Scan with deep CI include resolution
sentinel audit /path/to/your/repo --module cicd --deep-include
```

---

## Modules

| Module | What it checks |
|--------|---------------|
| **CI/CD** (deep) | `.gitlab-ci.yml` — OWASP CI/CD Top 10, missing security stages, hardcoded secrets, PPE risks, runner config, artifact integrity |
| **SCM** | Git history, CODEOWNERS, LICENSE, .gitignore patterns, tracked sensitive files, unsigned commits |
| **Secrets** | 150+ regex patterns + Shannon entropy across all repo files; optional git history scan |
| **Dependencies** | npm, pip, Go, Cargo, Ruby — CVEs via OSV.dev (no API key), lockfile enforcement, license compliance |

---

## Compliance Frameworks

Each finding maps to one or more controls from:
- **SOC 2** Trust Service Criteria (CC6.x, CC7.x, CC8.x)
- **CIS Benchmarks** (CIS GitLab, CIS Software Supply Chain)
- **OWASP CI/CD Security Top 10** (CICD-SEC-1 through CICD-SEC-10)
- **ISO 27001:2022** Annex A

---

## Configuration

Generate an example config:
```bash
sentinel init
```

The `sentinel.yml` controls all scan behaviour. CLI flags override config values.

```yaml
version: "1.0"
client:
  name: "Acme Corp"
scan:
  modules: [cicd, scm, secrets, deps]
cicd:
  deep_include: false
  required_stages: [sast, secret_detection, dependency_scanning]
deps:
  ecosystems: [npm, pip]
  ignore_cves: []
secrets:
  scan_history: false
reporting:
  formats: [json, pdf]
  output_dir: ./sentinel-reports
```

---

## Output

All formats are generated from the same findings data:

| Format | Use case |
|--------|----------|
| `json` | Machine-readable, CI integration, further processing |
| `markdown` | GitLab issues/wikis, inline review |
| `html` | Standalone browser report, dark/light theme |
| `pdf` | Client-facing branded report for CTO presentation |

```bash
sentinel audit . --format json --format pdf --format markdown
```

---

## Security Design

- **Zero credential storage** — authentication via environment variables only
- **Read-only** — Sentinel never modifies any scanned resource
- **Secret redaction** — detected secrets are shown as `abcd****wxyz` in all output
- **Artifact cleanup** — raw scan data in `.sentinel/collected/` is purged after reporting (use `--keep-artifacts` to retain)

---

## Development

```bash
bash scripts/setup-dev.sh
source .venv/bin/activate
pytest
ruff check sentinel/
mypy sentinel/
```

---

## License

Sentinel is open source under the [GNU Affero General Public License v3.0](LICENSE).

For commercial use cases that require redistribution or proprietary integration, including potential additional features and active/passive support, a commercial license is available upon contact with lead developer/maintainer.