drghassen/pfe-mpssr

1. Repo purpose

CloudSentinel is a DevSecOps framework for Azure that combines:

- shift-left preventive scanning and policy checks,

- shift-right drift detection and runtime remediation,

- OPA for decision logic,

- DefectDojo as the findings/exceptions backend,

- Azure Terraform infrastructure for the demo/deployment environment.

2. Top-level architecture

The repository is organized around three main planes:

- shift-left/: source, container, and IaC scanning before deployment.

- shift-right/: continuous drift/prowler/custodian enforcement after deployment.

- policies/ + config/: shared decision and exception definitions used by both planes.

3. Shift-left subsystem

This is the pre-deployment security pipeline. It includes scanners and normalizers for:

- Checkov custom Azure policy catalog,

- Trivy filesystem/config/image scanning,

- Gitleaks secret scanning,

- Cloud-init scanner for malicious initialization patterns,

- OPA gate decisions,

- report normalization and upload to DefectDojo.

The scripts under ci/scripts/shift-left/ orchestrate these steps in CI.

4. Shift-right subsystem

This is the runtime control loop for deployed Azure resources. It includes:

- drift-engine: detects configuration drift and builds remediation/detection reports,

- Prowler Azure checks for security posture,

- Custodian policies for enforcement/remediation,

- exception fetching and gate enforcement logic,

- uploads of drift/prowler results to DefectDojo.

The scripts under ci/scripts/shift-right/ connect the components into the runtime pipeline.

5. Policy and decision layer

The policies/opa/ tree is the central policy engine:

- gate/: pre-deploy approvals/denials and intent-based gating,

- drift/: drift classification, severity, exceptions, and remediation reasoning,

- prowler/: security finding evaluation and severity actions,

- system/: authorization rules for policy access.

Tests are colocated as .rego test files. These policies form the architecture’s “decision boundary” between raw scanner output and actionable security outcomes.

6. Exception and contract model

Exceptions are first-class artifacts, not ad hoc overrides:

- config/opa/data/exceptions.json and drift_exceptions.json feed policy evaluation,

- ci/contracts/*.json define artifact and integrity contracts,

- shift-left/opa/schema/exceptions_v2.schema.json and other schemas validate structure,

- verification/ contains runtime-state validation for shift-right integrity.

This means findings, exceptions, and remediation state are governed by explicit contracts.

7. Report normalization and data flow

Raw scanner outputs are normalized into CloudSentinel-specific schemas before policy evaluation or storage:

- shift-left/normalizer/ converts scanner results into a common report format,

- shift-right/drift-engine/utils/json_normalizer.py and related modules normalize drift/OPA outputs,

- schemas under shift-left/normalizer/schema/ and shift-right/drift-engine/schemas/ define the canonical shapes.

The architecture depends on normalization to keep scanners interchangeable.

8. Infrastructure boundary

infra/azure/ provides Terraform modules for the Azure environment:

- networking, identity, key vault, storage, database/cosmos, compute, container instances, RBAC, recovery, resource groups.

The compute module includes cloud-init templates, which ties infrastructure provisioning to the shift-left cloud-init scanner and the runtime drift model.

This is the main cloud boundary where the security framework is exercised.

9. Containerized toolchain

ci/images/ defines dedicated Docker images for repeatable CI/runtime execution:

- opa, prowler-tools, scan-tools, deploy-tools, custodian-tools, aci-runtime.

These images isolate scanner dependencies and make the CI pipeline deterministic. The GitLab CI files at the root orchestrate building and using those images.

10. Local integration and support tooling

docker-compose.yml, demosecrets/, and scripts/ support local demos and operational tasks:

- fetching exceptions from DefectDojo,

- creating risk acceptance artifacts,

- audit/notification utilities,

- bootstrap scripts for OPA auth and CA setup.

These are support boundaries around the core scanning/remediation flows.

11. Security taxonomy and mapping

Several directories exist to map findings into a unified security vocabulary:

- shift-right/drift-engine/utils/security_taxonomy.py,

- shift-left/normalizer/cs_norm_mappings.py,

- config/remediation-capabilities.json,

- ci/scripts/shift-right/correlation_mappings.json.

This indicates the architecture is designed to correlate different tools’ findings to common control, severity, and remediation categories.

12. Main end-to-end flows

- Shift-left flow: source/IaC/artifacts → scanner execution → normalization → OPA decisioning → contract checks / DefectDojo upload.

- Shift-right flow: live Azure state → drift/prowler/custodian evaluation → OPA decisions and exception matching → gate/remediation/enforcement → DefectDojo/reporting.

The architecture centers on these two loops, with OPA and normalized schemas acting as the integration backbone.

13. Operational emphasis

The presence of CI pipelines, build scripts, schemas, tests, and integrity contracts shows this repo is not just policy code; it is a full operational framework with strong emphasis on reproducibility, policy governance, and traceable security state.