<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Security Posture Scoring — API Reference

## AWS Security Hub Score

```python
import boto3

securityhub = boto3.client("securityhub")

# Get security score
resp = securityhub.get_findings(Filters={
    "ComplianceStatus": [{"Value": "PASSED", "Comparison": "EQUALS"}],
})

# Get standards compliance
resp = securityhub.get_enabled_standards()
for standard in resp["StandardsSubscriptions"]:
    controls = securityhub.describe_standards_controls(
        StandardsSubscriptionArn=standard["StandardsSubscriptionArn"]
    )
```

## Azure Secure Score

```python
import requests

GRAPH_URL = "https://graph.microsoft.com/v1.0"
TOKEN = "Bearer your-token"

# Get secure score
resp = requests.get(f"{GRAPH_URL}/security/secureScores",
    headers={"Authorization": TOKEN}, params={"$top": 1})

# Get secure score profiles
resp = requests.get(f"{GRAPH_URL}/security/secureScoreControlProfiles",
    headers={"Authorization": TOKEN})
```

## Qualys CSAM Posture

```python
resp = requests.get("https://qualysapi.qualys.com/csam/v1/assets/score",
    auth=("user", "pass"), params={"scope": "all"})
```

## Scoring Model

```
composite_score = Σ (domain_score × domain_weight)

Domain Weights:
  vulnerability_management: 0.25
  identity_access:          0.20
  endpoint_protection:      0.20
  network_security:         0.15
  data_protection:          0.10
  incident_response:        0.10

Grade Scale:
  A: 90-100 | B: 80-89 | C: 70-79 | D: 60-69 | F: <60
```

## Trend Analysis

```python
# Simple moving average for smoothing
def sma(scores: list[float], window: int = 3) -> list[float]:
    return [sum(scores[i:i+window])/window for i in range(len(scores)-window+1)]

# Month-over-month change
def mom_change(scores: list[float]) -> list[float]:
    return [round(scores[i]-scores[i-1], 1) for i in range(1, len(scores))]
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Score calculated — healthy (grade A/B) |
| 1 | Score calculated — attention needed (grade C) |
| 2 | Score calculated — critical (grade D/F) |
