Add explainable multicloud vulnerability scoring

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: coverage run -m unittest discover -v
+      - run: coverage report
+      - run: python -m build
+

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.coverage
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+report*.json
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Alan Nogueira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include SECURITY.md
+recursive-include docs *.md
+recursive-include examples *.json
+recursive-include tests *.py

SECURITY.md

@@ -0,0 +1,34 @@
+# Segurança
+
+## Modelo operacional
+
+A versão `0.1.0` processa exportações JSON locais. Ela não solicita credenciais cloud e não chama
+APIs da AWS, Azure ou Google Cloud.
+
+Use somente exportações obtidas com autorização. Achados podem conter identificadores de contas,
+assinaturas, projetos, recursos, topologia e vulnerabilidades ainda não corrigidas.
+
+## Proteção dos relatórios
+
+- identificadores de achados e recursos são pseudonimizados;
+- títulos e descrições originais não são gravados;
+- relatórios são publicados atomicamente;
+- em sistemas POSIX, o arquivo recebe modo `0600`;
+- um segredo HMAC pode ser fornecido em `CLOUD_AUDIT_HMAC_SECRET`;
+- o relatório continua confidencial mesmo com pseudonimização.
+
+Não publique exportações reais, relatórios ou segredos em commits, issues ou pull requests.
+
+## Limites
+
+- entrada máxima de 20 MiB;
+- links simbólicos são rejeitados;
+- não há execução de remediação;
+- não há autenticação ou coleta automática nesta versão;
+- o score não substitui análise de risco, pentest ou resposta a incidentes.
+
+## Comunicação responsável
+
+Não abra issue pública contendo dados do ambiente ou detalhes de uma vulnerabilidade explorável.
+Use um canal privado previamente combinado com o mantenedor.
+

docs/SCORING.md

@@ -0,0 +1,56 @@
+# Metodologia de score
+
+Versão: `cloud-risk-1.0.0`.
+
+O score é uma regra de priorização criada por este projeto. Ele não corresponde ao AWS Security
+Hub score, Microsoft Secure Score ou Google Cloud Security Command Center score. Também não
+conclui conformidade, comprometimento ou aceitabilidade do risco.
+
+## Score por achado
+
+| Fator | Pontos |
+|---|---:|
+| Severidade informativa | 0 |
+| Severidade baixa | 10 |
+| Severidade média | 25 |
+| Severidade alta | 45 |
+| Severidade crítica | 70 |
+| Severidade desconhecida | 15 |
+| Prova de conceito disponível | +5 |
+| Exploit funcional | +10 |
+| Exploração conhecida | +20 |
+| Exposição pública explícita | +15 |
+| Contexto privilegiado explícito | +10 |
+| Dados sensíveis explícitos | +10 |
+| Mais de 90 dias | +5 |
+| Mais de 180 dias | +10 |
+| Controle compensatório explícito | -10 |
+
+O resultado é limitado ao intervalo de 0 a 100. Achados resolvidos, inativos, saudáveis,
+arquivados ou não aplicáveis recebem zero.
+
+## Faixas
+
+- 0: informativo;
+- 1 a 19: baixo;
+- 20 a 39: médio;
+- 40 a 69: alto;
+- 70 a 100: crítico.
+
+## Score do ambiente
+
+Somente achados ativos com pontuação positiva entram no cálculo:
+
+```text
+environment_score = 50% maior risco
+                  + 35% média dos 10 maiores riscos
+                  + 15% proporção de achados críticos
+```
+
+O desenho evita que uma grande quantidade de alertas baixos esconda um achado crítico.
+
+## Confiança
+
+`confidence_score` mede completude da evidência, não risco. Fonte reconhecida, severidade, estado,
+identificador do recurso, identificador do achado, timestamp e sinais contextuais contribuem para
+a confiança. A confiança nunca é somada ao risco.

examples/aws-securityhub.json

@@ -0,0 +1,22 @@
+{
+  "Findings": [
+    {
+      "SchemaVersion": "2018-10-08",
+      "Id": "synthetic-aws-finding-001",
+      "Title": "Synthetic internet exposed storage finding",
+      "Types": ["Software and Configuration Checks/Synthetic"],
+      "Severity": {"Label": "HIGH"},
+      "Workflow": {"Status": "NEW"},
+      "RecordState": "ACTIVE",
+      "UpdatedAt": "2026-08-01T00:00:00Z",
+      "Resources": [
+        {"Id": "arn:aws:s3:::synthetic-audit-bucket", "Type": "AwsS3Bucket"}
+      ],
+      "ProductFields": {
+        "cloud-audit/public_exposure": "true",
+        "cloud-audit/sensitive_data": "true"
+      }
+    }
+  ]
+}
+

examples/azure-defender.json

@@ -0,0 +1,16 @@
+{
+  "value": [
+    {
+      "id": "/subscriptions/00000000/providers/Microsoft.Security/assessments/synthetic-001",
+      "name": "synthetic-001",
+      "type": "Microsoft.Security/assessments",
+      "properties": {
+        "status": {"code": "Unhealthy", "statusChangeDate": "2026-08-01T00:00:00Z"},
+        "metadata": {"displayName": "Synthetic exposed management port", "severity": "Critical"},
+        "resourceDetails": {"id": "/subscriptions/00000000/resourceGroups/synthetic/providers/Microsoft.Compute/virtualMachines/vm-001"},
+        "additionalData": {"public_exposure": true, "privileged": true}
+      }
+    }
+  ]
+}
+

examples/gcp-scc.json

@@ -0,0 +1,17 @@
+{
+  "listFindingsResults": [
+    {
+      "finding": {
+        "name": "organizations/000000/sources/000000/findings/synthetic-001",
+        "resourceName": "//compute.googleapis.com/projects/synthetic/zones/us-central1-a/instances/vm-001",
+        "category": "PUBLIC_IP_ADDRESS",
+        "state": "ACTIVE",
+        "severity": "HIGH",
+        "eventTime": "2026-08-01T00:00:00Z",
+        "sourceProperties": {"public_exposure": true}
+      },
+      "resource": {"type": "google.compute.Instance"}
+    }
+  ]
+}
+

pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cloud-vulnerability-audit"
+version = "0.1.0"
+description = "Deterministic multicloud finding normalization and risk scoring"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Alan Nogueira"}]
+keywords = ["cloud-security", "audit", "grc", "aws", "azure", "gcp"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "coverage>=7.6",
+  "ruff>=0.8",
+]
+
+[project.scripts]
+cloud-vulnerability-audit = "cloud_vulnerability_audit.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]
+
+[tool.coverage.run]
+source = ["cloud_vulnerability_audit"]
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true

src/cloud_vulnerability_audit/__init__.py

@@ -0,0 +1,8 @@
+"""Deterministic multicloud vulnerability prioritization."""
+
+from cloud_vulnerability_audit.models import Finding, ScoredFinding
+from cloud_vulnerability_audit.scoring import SCORING_VERSION, score_finding
+
+__all__ = ["Finding", "SCORING_VERSION", "ScoredFinding", "score_finding"]
+__version__ = "0.1.0"
+

src/cloud_vulnerability_audit/__main__.py

@@ -0,0 +1,4 @@
+from cloud_vulnerability_audit.cli import main
+
+raise SystemExit(main())
+