OpenShield

Open source Cloud Security Posture Management (CSPM) for Azure — built by the community, for the community.

---

The Problem

Enterprise cloud security tools like Wiz, Prisma Cloud, and Microsoft Defender for Cloud cost $50,000–$500,000/year.

Startups, SMEs, universities, and student teams are left with zero visibility into their Azure security posture. A misconfigured storage blob, an overprivileged service principal, or an open NSG rule can sit undetected for months.

OpenShield changes that.

---

What OpenShield Does

Feature	Description
Misconfiguration Scanner	Runs 20 Azure security rules across storage, network, identity, database, compute, and Key Vault
Compliance Mapper	Maps findings to CIS Benchmarks, NIST CSF, ISO 27001, and SOC 2 framework JSON files
Scan History API	Stores scans and findings in PostgreSQL and exposes findings, score, scan history, and compliance posture over REST
Remediation Playbooks	Every current rule ships with a matching Azure CLI remediation script
Security Dashboard	Frontend scaffold is present; the React dashboard MVP is still on the roadmap
Sentinel Integration	Normalises findings and pushes them into Microsoft Sentinel via a Log Analytics custom table and KQL analytics rules

---

Architecture

flowchart TD
    A["React Dashboard MVP\nPlanned frontend"]
    B["Flask REST API\nJWT · CORS · Blueprints"]
    C["Scanner Engine\n20 Python rules"]
    D["Azure Subscription\nScanned via Azure SDK + Graph"]
    E["Compliance Framework JSON\nCIS · NIST · ISO 27001 · SOC 2"]
    F["PostgreSQL Database\nFindings · Scans"]
    G["Azure CLI Playbooks\n20 remediation scripts"]
    H["sentinel/ingest.py\nNormalise + HMAC upload"]
    I["Microsoft Sentinel\nOpenShieldFindings_CL · KQL rules"]

    A -->|REST calls| B
    B -->|trigger scans| C
    B -->|read/write| F
    B -->|compliance score| E
    C -->|Azure SDK + Graph| D
    C -->|findings| F
    C -->|scan output JSON| H
    G -->|manual fixes| D
    H -->|Data Collector API| I
    I -->|alerts| A

Loading

Live API

The OpenShield API is deployed to the Render free tier and is accessible at:

https://openshield-api.onrender.com

Note: As this is hosted on the Render free tier, the service may spin down after 15 minutes of inactivity. The first request after a spin-down can take 30-60 seconds to complete.

Important

Security Requirement: For absolute security, any production deployment must override the default JWT_SECRET with a strong, unique value in the environment variables.

---

Tech Stack

Layer	Technology	Cost
Frontend	Scaffolded dashboard app (React + Tailwind planned)	Free
Backend API	Python + Flask	Free
Database	PostgreSQL	Free (Render/Azure free tier)
Cloud Scanner	Python + Azure SDK	Free
Remediation	Azure CLI playbooks	Free
SIEM	Microsoft Sentinel	90-day free trial
CI/CD	GitHub Actions	Free
Repo	GitHub	Free

---

Project Structure

openshield/
├── scanner/               # Azure misconfiguration rule engine
│   ├── rules/             # Individual scan rules (contribute here!)
│   ├── engine.py          # Core scanning orchestration
│   └── azure_client.py    # Azure SDK wrapper
├── compliance/            # Framework mapping engine
│   └── frameworks/        # CIS, NIST, ISO 27001, SOC 2 mappings
├── playbooks/             # Remediation playbooks
│   ├── arm/               # Reserved for future ARM templates
│   ├── terraform/         # Reserved for future Terraform fixes
│   └── cli/               # Azure CLI scripts
├── api/                   # Flask REST API
│   ├── routes/
│   └── models/
├── frontend/              # Dashboard scaffold
├── sentinel/              # Sentinel integration & KQL rules
├── .github/workflows/     # CI checks
├── docs/                  # Documentation
├── CONTRIBUTING.md
└── README.md

---

Quick Start

# Clone the repo
git clone https://github.com/openshield-org/openshield.git
cd openshield

# Install Python dependencies
pip install -r requirements.txt

# Set your Azure credentials
export AZURE_SUBSCRIPTION_ID=your-subscription-id
export AZURE_CLIENT_ID=your-client-id
export AZURE_CLIENT_SECRET=your-client-secret
export AZURE_TENANT_ID=your-tenant-id

# Run a scan
python -c "
from scanner.engine import ScanEngine
import json, os
result = ScanEngine(os.environ['AZURE_SUBSCRIPTION_ID']).run_scan()
print(json.dumps(result, indent=2))
"

# Start the API
FLASK_APP=api/app.py flask run

---

Contributing

We actively welcome contributions from students and developers at all levels.

Ways to contribute:

• Add a new misconfiguration scan rule
• Add a compliance framework mapping
• Write a remediation playbook
• Fix a bug
• Improve documentation

See CONTRIBUTING.md for a full guide — including how to add your first rule in under 30 minutes.

Contributors are credited below.

---

Roadmap

• Project scaffolding
• Core scanner engine (Azure SDK integration)
• 20 scan rules
• Flask API + PostgreSQL schema
• React dashboard MVP
• CIS Benchmark compliance mapping
• SOC 2 compliance mapping
• Sentinel alert integration
• Real-world breach scenarios documented
• First external contributor PR merged
• Azure CLI remediation playbook library
• NIST CSF + ISO 27001 mappings
• GitHub Actions CI pipeline
• Multi-cloud support (AWS, GCP)

---

License

MIT — free to use, modify, and distribute.

---

Built by security engineers and students who believe cloud security tooling should be accessible to everyone.