Misconfiguration scanning
Dynamic Python rule modules inspect Azure resources through Azure SDK clients and return normalized security findings.
ScannerAzure SDKRules
Overview
What OpenShield does
OpenShield is built to help users identify risky Azure configurations, understand the impact, connect findings to compliance controls, and follow practical remediation guidance. It is not a cloud provider replacement or a SIEM; it is a focused Azure CSPM platform for posture visibility and learning.
CVE enrichment
Findings can be enriched with NVD/CVE context so security issues are easier to prioritize and explain.
NVDCVERisk context
Compliance mapping
Technical findings are mapped to CIS Azure, NIST CSF, ISO 27001, and SOC 2 for governance-oriented reporting.
CISNISTISO 27001SOC 2
Remediation guidance
Each rule is paired with a CLI playbook so contributors and users can move from detection to manual remediation.
Azure CLIPlaybooksValidation
Architecture
Production-shaped, MVP-friendly architecture
The platform follows a simple pipeline: Azure credentials are resolved by DefaultAzureCredential, the scan engine loads
rule files from scanner/rules/*.py, findings are enriched and stored, then exposed through the API and dashboard.
Azure SubscriptionResources and configuration
Scanner EnginePython rule execution
Rule Evaluation39 dynamic checks
CVE EnrichmentNVD risk context
PostgreSQLFindings and scan history
Flask APIJWT-protected REST routes
React DashboardDemo and live modes
Sentinel / AIKQL, RAG, insights
Scanner
Core engine, Azure SDK wrapper, NVD/CVE enrichment, and auto-loaded rule files.
API
Flask REST API with JWT authentication, CORS, migrations, scans, findings, score, compliance, and AI routes.
Frontend
Vite, React, and Tailwind dashboard covering monitoring, discovery, prioritization, compliance, drift, and AI.
AI
RAG knowledge pipeline, ChromaDB vector store builder, retriever, and cloud-security knowledge skills.
Sentinel
Optional Log Analytics ingestion plus KQL analytics rules for detection workflows.
CI and docs
Checks syntax, secrets, rule structure, playbooks, compliance JSON, API syntax, and cross-references.
Rule coverage
39 Azure security rules
OpenShield currently has 39 dynamic rules. The strongest contributor work improves rule accuracy, reduces false positives, strengthens validation, or improves remediation quality.
Coverage by category
Severity distribution
Most checks are high severity. That makes validation important: high-severity false positives damage trust quickly.
22HIGH
13MEDIUM
4LOW
Known cleanup item: keep category names consistent, especially KeyVault vs Key Vault.
Learning roadmap
Recommended learning path
Follow this path if you are new to OpenShield or preparing to contribute. Learn the security problem before touching code.
Azure security fundamentals
Understand subscriptions, identities, resources, networking, storage, Key Vault, and logging.
ReadCSPM concepts
Learn how posture tools detect insecure cloud configuration and why false positives matter.
ReadOpenShield architecture
Trace the flow from Azure SDK collection to scanner rules, enrichment, storage, API, and dashboard.
ReadRule engineering
Study rule structure, metadata, severity, categories, and safe test scenarios.
ReadCompliance mapping
Map technical findings to CIS, NIST CSF, ISO 27001, and SOC 2 without forcing weak mappings.
ReadRemediation playbooks
Write CLI guidance that fixes the issue and includes validation commands.
ReadSentinel integration
Understand optional Log Analytics ingestion and KQL analytics rules for security monitoring.
ReadAI security features
Review the RAG pipeline, knowledge loaders, retriever, and AI insight routes.
ReadFind topics
Search this learning page
Contributors
Where contributors can help
Good contributions should improve detection accuracy, correctness of findings, remediation quality, documentation clarity, or system reliability. Cosmetic work is useful only when it supports those goals.
Rules
Add or improve Azure checks with accurate metadata, safe SDK usage, realistic test cases, and clear findings.
Playbooks
Keep remediation scripts aligned with rules. Every fix should include validation and avoid unsafe blanket changes.
Compliance
Improve CIS, NIST, ISO 27001, and SOC 2 mappings. Do not map controls just to inflate coverage.
Frontend
Connect live API flows carefully. Do not leave mock-backed UI pretending to be production data.
Backend
Implement missing endpoints consistently with JWT auth, error handling, data contracts, and PostgreSQL models.
AI and Sentinel
Improve RAG quality, knowledge loading, KQL rules, and ingestion without exposing sensitive findings unnecessarily.
Known gaps
Current cleanup items
These are not failures; they are useful follow-up targets. Documenting them prevents contributors from pretending the platform is more complete than it is.
Documentation drift
- Some README/docs references still mention 20 rules while the repo has 39.
- Some startup commands assume
python, but local environments may only exposepython3. - API docs and implementation should stay aligned, especially score response shape.
Implementation gaps
- Some frontend live pages depend on endpoints that may still be mock-backed.
- Examples include resources, drift, prioritization, and finding-specific playbook routes.
- Fix syntax issues before claiming AI pipeline readiness.
Documentation
Useful repo documents
These relative links are intentionally static-hosting friendly when this file is served from the docs learning folder. Adjust paths if the Learn page is moved.
ArchitectureSystem design, scanner flow, platform components, and storage/API structure.
Open
API ReferenceBackend routes for scans, findings, score, compliance, and AI-related data.
Open
Azure SetupEnvironment variables, Azure credentials, and setup requirements for live scans.
Open
Rules ReferenceRule metadata, categories, severity, expected output, and implementation guidance.
Open
Adding a RuleContributor workflow for implementing, testing, and documenting a new check.
Open
CI PipelineLocal and GitHub Actions checks for rules, playbooks, compliance JSON, and API syntax.
Open
CVE CorrelationNVD enrichment, CVSS scoring, exploit availability, and dashboard-ready CVE fields.
Open
Sentinel SetupLog Analytics ingestion, OpenShield findings table setup, and KQL analytics rules.
Open
API Render DeployRender deployment test plan, smoke testing, and production JWT requirements.
Open
AZ-STOR-003 Test PlanLifecycle management policy rule test setup, execution, remediation, and validation.
Open
Note: OpenShield Learn is a documentation and learning portal. Features such as authentication, file uploads, scan execution, and data persistence require backend services and are intentionally not implemented in this static site.