diff --git a/README.md b/README.md index 2c72564..de0b752 100644 --- a/README.md +++ b/README.md @@ -243,6 +243,16 @@ MIT — free to use, modify, and distribute. ## Learn OpenShield +Learn OpenShield covers: + +- Azure CSPM fundamentals +- OpenShield architecture +- Compliance mappings +- Remediation workflows +- Contributor onboarding +- Documentation navigation + +Live Learning Portal: https://openshieldlearn.netlify.app/learn/ Full documentation, the security rules gallery, blog, and interactive playground are available at the project website: **[openshield-website.vercel.app](https://openshield-website.vercel.app)** diff --git a/docs/_redirects b/docs/_redirects new file mode 100644 index 0000000..fe0b625 --- /dev/null +++ b/docs/_redirects @@ -0,0 +1 @@ +/ /learn/ 302 diff --git a/docs/learn/index.html b/docs/learn/index.html index 93c5164..7ca6219 100644 --- a/docs/learn/index.html +++ b/docs/learn/index.html @@ -3,64 +3,199 @@ + OpenShield Learn -
-
Open Source Azure CSPM Platform
-

OpenShield Learn

-

- A practical learning hub for understanding OpenShield, Azure cloud security posture management, - misconfiguration detection, compliance mapping, drift detection, and remediation workflows. -

-
- Architecture - Learn CSPM - Contributing - Docs -
-
+ -
-
-

What is OpenShield?

-

- OpenShield is an open-source Azure CSPM platform designed to identify cloud misconfigurations, - map findings to compliance frameworks, monitor posture drift, and provide remediation guidance. It helps users understand - what is insecure, why it matters, and how to fix it. -

-
-
-

Misconfiguration Scanning

-

Checks Azure resources for risky settings that can expose data, weaken access control, or reduce security visibility.

-
-
-

Compliance Mapping

-

Connects security findings to frameworks such as CIS, NIST, and ISO so issues can be understood in a governance context.

+
+ +
+ +
+
+
+
Open-source Azure CSPM platform
+

Learn Azure security posture with OpenShield.

+

+ OpenShield scans Azure subscriptions for misconfigurations, enriches findings with CVE intelligence, + maps risks to compliance frameworks, stores scan history, exposes a Flask API, and presents results through + a React dashboard with demo and live modes. +

+
+ Start learning + View rule coverage + Contributor path
-
-

Remediation Guidance

-

Provides practical fix guidance using Azure CLI, ARM templates, Terraform, and validation checks where applicable.

+

Static learning hub. No backend, no login, no fake upload flows.

+
+ + +
+ +
+
39Azure scan rules
+
39CLI remediation playbooks
+
4Compliance frameworks
+
8AI security skills
+
22High-severity checks
+
+
+ +
+
+
+
+

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. +

+ +
+
+

Misconfiguration scanning

+

Dynamic Python rule modules inspect Azure resources through Azure SDK clients and return normalized security findings.

+
ScannerAzure SDKRules
+
+
+

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
+
+
-
-

How OpenShield Works

+
+

Architecture

+

Production-shaped, MVP-friendly architecture

- OpenShield follows a simple scanning pipeline: collect Azure resource configuration, evaluate rules, - generate findings, map them to controls, and expose results through the platform. + 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 Subscription
-
Scanner Engine
-
Rule Evaluation
-
Findings
-
Compliance Mapping
-
Drift Detection
-
Dashboard & Reporting
+ +
+
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.

-
-

Core Components

+
+

Rule coverage

+

39 Azure security rules

- OpenShield is built with a simple MVP-friendly architecture: Python scanner, Flask API, - PostgreSQL storage, React frontend, compliance mapping, Sentinel integration, and supporting remediation playbooks. + OpenShield currently has 39 dynamic rules. The strongest contributor work improves rule accuracy, reduces false positives, + strengthens validation, or improves remediation quality.

-
-
-

Scanner Engine

-

Python-based scanner that uses Azure SDK clients to inspect Azure resource configuration and evaluate security rules.

- PythonAzure SDK -
-
-

Flask API

-

Backend API layer responsible for exposing scan results, findings, metadata, and platform data to the frontend.

- FlaskREST API -
-
-

PostgreSQL

-

Stores scan findings, rule metadata, compliance mappings, and remediation-related information.

- DatabasePersistence -
-
-

React Dashboard

-

Frontend dashboard for viewing findings, severity, affected resources, and security posture information.

- ReactDashboard -
-
-

Playbooks

-

Remediation documents that explain how to fix detected issues using CLI, ARM templates, Terraform, and validation steps.

- Azure CLIARMTerraform -
-
-

Sentinel

-

Supports security monitoring and SIEM-focused documentation where OpenShield findings connect with detection workflows.

- SIEMDetection -
+ +
+
+

Coverage by category

+
+
Network
14
+
Storage
5
+
Key Vault
5
+
Compute
4
+
Database
4
+
Identity
4
+
PostQuantum
3
+
+
+ +
+

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.

+
-
-

CSPM Basics

+
+

Learning roadmap

+

Recommended learning path

- Cloud Security Posture Management focuses on continuously identifying insecure cloud configurations. - In Azure, common examples include public storage exposure, weak network rules, missing logging, - overly permissive identities, and disabled security protections. + Follow this path if you are new to OpenShield or preparing to contribute. Learn the security problem before touching code.

-
-
-

Why It Matters

-

Cloud breaches often happen because resources are misconfigured, not because the cloud provider itself failed.

-
-
-

Example Issues

-
    -
  • Public blob access
    • -
  • Weak network security groups
    • -
  • Missing monitoring or logging
    • -
  • Over-permissive access policies
    • -
-
-
-

OpenShield Role

-

OpenShield helps surface these issues, explain their impact, and guide users toward safer Azure configurations.

-
+ +
+

Azure security fundamentals

Understand subscriptions, identities, resources, networking, storage, Key Vault, and logging.

Read +

CSPM concepts

Learn how posture tools detect insecure cloud configuration and why false positives matter.

Read +

OpenShield architecture

Trace the flow from Azure SDK collection to scanner rules, enrichment, storage, API, and dashboard.

Read +

Rule engineering

Study rule structure, metadata, severity, categories, and safe test scenarios.

Read +

Compliance mapping

Map technical findings to CIS, NIST CSF, ISO 27001, and SOC 2 without forcing weak mappings.

Read +

Remediation playbooks

Write CLI guidance that fixes the issue and includes validation commands.

Read +

Sentinel integration

Understand optional Log Analytics ingestion and KQL analytics rules for security monitoring.

Read +

AI security features

Review the RAG pipeline, knowledge loaders, retriever, and AI insight routes.

Read
-
-

Compliance Mapping

-

- A single security finding can map to multiple compliance controls. OpenShield uses mappings to connect - technical misconfigurations with security frameworks such as CIS Benchmarks, NIST CSF, ISO 27001, and SOC 2. -

-
-

CIS

Maps findings to cloud security benchmarks and configuration recommendations.

-

NIST

Connects findings to broader cybersecurity controls and risk management practices.

-

ISO 27001

Supports governance, information security controls, and audit-oriented reporting context.

-

SOC 2

Connects relevant findings to trust-service control areas such as security, availability, and confidentiality.

+ -
-

Remediation Philosophy

+
+

Contributors

+

Where contributors can help

- Detection alone is not enough. A useful CSPM tool should explain the risk, provide fix guidance, - and help validate whether the issue has actually been resolved. + 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.

+
-

Detect

Identify insecure Azure configuration accurately with minimal false positives.

-

Explain

Show why the finding matters, what resource is affected, and what the risk is.

-

Fix

Provide Azure CLI, ARM template, or Terraform-based remediation steps that users can apply safely.

-

Validate

Re-run checks or confirm settings to verify the misconfiguration is resolved.

+

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.

-
-

Contributor Learning Path

+
+

Known gaps

+

Current cleanup items

- New contributors should understand the security problem first, then the OpenShield architecture, - then the rule and remediation workflow. + These are not failures; they are useful follow-up targets. Documenting them prevents contributors from pretending the platform is more complete than it is.

-
-
-

Suggested Path

-
    -
  1. Understand CSPM fundamentals
    2. -
  2. Review the OpenShield architecture
    3. -
  3. Explore existing documentation and rules
    4. -
  4. Understand findings, mappings, and remediation playbooks
    5. -
  5. Add or improve rules and playbooks
    6. -
  6. Test changes against Azure safely
    7. -
-
-
-

Contribution Focus

-

Good contributions improve detection accuracy, remediation quality, documentation clarity, or platform reliability.

-
+ +
+
+

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 expose python3.
    • +
  • 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 Links

+
+

Documentation

+

Useful repo documents

- Use these links as the starting point for understanding and contributing to OpenShield. + 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, platform components, and scanning workflow.
- Open +
ArchitectureSystem design, scanner flow, platform components, and storage/API structure.
+ Open
-
API ReferenceBackend API documentation for working with OpenShield data.
- Open +
API ReferenceBackend routes for scans, findings, score, compliance, and AI-related data.
+ Open
-
Azure SetupRequired Azure setup and configuration before running scans.
- Open +
Azure SetupEnvironment variables, Azure credentials, and setup requirements for live scans.
+ Open
-
Rules ReferenceRule documentation and expected structure for security checks.
- Open +
Rules ReferenceRule metadata, categories, severity, expected output, and implementation guidance.
+ Open
-
Adding a RuleContributor guide for creating and testing new scan rules.
- 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
-
-

Open Source Goals

-

- OpenShield aims to make Azure security posture management easier to understand, easier to test, - and easier to improve through community contribution. -

-
-

Security Research

Encourage practical Azure misconfiguration research and rule development.

-

Education

Help learners understand CSPM, cloud controls, and secure Azure configuration.

-

Community

Build a contributor-friendly platform where improvements are clear and reviewable.

-
-
- -
-

Future Scope

-

- OpenShield can grow over time with richer dashboards, stronger compliance reports, - automated remediation workflows, and eventually broader cloud coverage. -

-
- -
- Note: This page is a static documentation hub. Do not add fake file upload buttons here. - Real uploads require backend storage, authentication, authorization, file validation, and access control. -
+
+ 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. +
- OpenShield — Open Source Azure CSPM Platform | Learn, Contribute, Improve Azure Security +
+

OpenShield — Open Source Azure CSPM Platform | Learn, Contribute, Improve Azure Security

+

Static Learn Portal

+
+ +