vulnsig 1.0.0__tar.gz

vulnsig-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: vulnsig
+Version: 1.0.0
+Summary: Render CVSS vulnerability vectors as expressive SVG glyphs
+License-Expression: MIT
+Project-URL: Homepage, https://vulnsig.io
+Project-URL: Repository, https://github.com/vulnsig/vulnsig-py
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cvss==3.6
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: ruff==0.15.0; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: nox==2025.11.12; extra == "dev"
+Requires-Dist: build==1.4.0; extra == "dev"
+
+# vulnsig-py
+
+Render CVSS vulnerability vectors as expressive SVG glyphs. Each glyph encodes all base metrics visually with shape, color, rings, and texture, so vulnerabilities are recognizable at a glance.
+
+Supports CVSS 4.0, 3.1, and 3.0.
+
+## Install
+
+```bash
+pip install vulnsig
+```
+
+## Usage
+
+```python
+from vulnsig import render_glyph
+
+svg = render_glyph("CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H")
+
+# override the score (e.g. if you already have it)
+svg = render_glyph("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H", score=10.0)
+
+# control rendered size in pixels (default 120)
+svg = render_glyph("CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N", size=64)
+```
+
+`render_glyph` returns an SVG string ready to embed in HTML or write to a file.
+
+## Examples
+
+### CVSS 4.0
+
+| Glyph | Name | Vector | Score |
+|:-----:|------|--------|------:|
+| <img src="assets/log4shell.svg" width="80"> | Log4Shell | `AV:N AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:H SI:H SA:H` | 10.0 |
+| <img src="assets/eternalblue.svg" width="80"> | EternalBlue | `AV:N AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:N SI:N SA:N` | 9.3 |
+| <img src="assets/heartbleed.svg" width="80"> | Heartbleed | `AV:N AC:L AT:N PR:N UI:N VC:H VI:N VA:N SC:L SI:N SA:N` | 8.7 |
+| <img src="assets/spectre.svg" width="80"> | Spectre | `AV:L AC:H AT:P PR:L UI:N VC:H VI:N VA:N SC:H SI:N SA:N` | 5.6 |
+| <img src="assets/xss-stored.svg" width="80"> | XSS Stored | `AV:N AC:L AT:N PR:L UI:P VC:L VI:L VA:N SC:N SI:N SA:N` | 5.1 |
+| <img src="assets/usb-physical.svg" width="80"> | USB Drop | `AV:P AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:N SI:N SA:N` | 7.3 |
+
+### CVSS 3.x
+
+| Glyph | Name | Vector | Score |
+|:-----:|------|--------|------:|
+| <img src="assets/log4shell-31.svg" width="80"> | Log4Shell | `AV:N AC:L PR:N UI:N S:C C:H I:H A:H` | 10.0 |
+| <img src="assets/xss-reflected-31.svg" width="80"> | XSS Reflected | `AV:N AC:L PR:N UI:R S:C C:L I:L A:N` | 6.1 |
+
+## Visual encoding
+
+Each metric maps to a distinct visual channel:
+
+| Metric | Channel |
+|--------|---------|
+| Score | Hue — yellow (low) → orange → dark red (high) |
+| AV | Star points — N=8, A=6, L=4, P=3 |
+| AC | Star pointiness — L=sharp, H=blunt |
+| AT | Ring segmentation — N=solid, P=cut pattern |
+| PR | Star outline — N=none, L=thin, H=thick |
+| UI | Perimeter — N=spikes, P=bumps, A=clean |
+| VC/VI/VA | Inner ring brightness per sector |
+| SC/SI/SA | Outer ring band (split when any > 0) |
+
+## Requirements
+
+Python 3.10+

vulnsig-1.0.0/README.md

@@ -0,0 +1,66 @@
+# vulnsig-py
+
+Render CVSS vulnerability vectors as expressive SVG glyphs. Each glyph encodes all base metrics visually with shape, color, rings, and texture, so vulnerabilities are recognizable at a glance.
+
+Supports CVSS 4.0, 3.1, and 3.0.
+
+## Install
+
+```bash
+pip install vulnsig
+```
+
+## Usage
+
+```python
+from vulnsig import render_glyph
+
+svg = render_glyph("CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H")
+
+# override the score (e.g. if you already have it)
+svg = render_glyph("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H", score=10.0)
+
+# control rendered size in pixels (default 120)
+svg = render_glyph("CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N", size=64)
+```
+
+`render_glyph` returns an SVG string ready to embed in HTML or write to a file.
+
+## Examples
+
+### CVSS 4.0
+
+| Glyph | Name | Vector | Score |
+|:-----:|------|--------|------:|
+| <img src="assets/log4shell.svg" width="80"> | Log4Shell | `AV:N AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:H SI:H SA:H` | 10.0 |
+| <img src="assets/eternalblue.svg" width="80"> | EternalBlue | `AV:N AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:N SI:N SA:N` | 9.3 |
+| <img src="assets/heartbleed.svg" width="80"> | Heartbleed | `AV:N AC:L AT:N PR:N UI:N VC:H VI:N VA:N SC:L SI:N SA:N` | 8.7 |
+| <img src="assets/spectre.svg" width="80"> | Spectre | `AV:L AC:H AT:P PR:L UI:N VC:H VI:N VA:N SC:H SI:N SA:N` | 5.6 |
+| <img src="assets/xss-stored.svg" width="80"> | XSS Stored | `AV:N AC:L AT:N PR:L UI:P VC:L VI:L VA:N SC:N SI:N SA:N` | 5.1 |
+| <img src="assets/usb-physical.svg" width="80"> | USB Drop | `AV:P AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:N SI:N SA:N` | 7.3 |
+
+### CVSS 3.x
+
+| Glyph | Name | Vector | Score |
+|:-----:|------|--------|------:|
+| <img src="assets/log4shell-31.svg" width="80"> | Log4Shell | `AV:N AC:L PR:N UI:N S:C C:H I:H A:H` | 10.0 |
+| <img src="assets/xss-reflected-31.svg" width="80"> | XSS Reflected | `AV:N AC:L PR:N UI:R S:C C:L I:L A:N` | 6.1 |
+
+## Visual encoding
+
+Each metric maps to a distinct visual channel:
+
+| Metric | Channel |
+|--------|---------|
+| Score | Hue — yellow (low) → orange → dark red (high) |
+| AV | Star points — N=8, A=6, L=4, P=3 |
+| AC | Star pointiness — L=sharp, H=blunt |
+| AT | Ring segmentation — N=solid, P=cut pattern |
+| PR | Star outline — N=none, L=thin, H=thick |
+| UI | Perimeter — N=spikes, P=bumps, A=clean |
+| VC/VI/VA | Inner ring brightness per sector |
+| SC/SI/SA | Outer ring band (split when any > 0) |
+
+## Requirements
+
+Python 3.10+

vulnsig-1.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vulnsig"
+version = "1.0.0"
+description = "Render CVSS vulnerability vectors as expressive SVG glyphs"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+
+dependencies = [
+    "cvss==3.6",
+]
+
+[project.urls]
+Homepage = "https://vulnsig.io"
+Repository = "https://github.com/vulnsig/vulnsig-py"
+
+[project.optional-dependencies]
+dev = [
+    "pytest==9.0.2",
+    "ruff==0.15.0",
+    "mypy==1.19.1",
+    "nox==2025.11.12",
+    "build==1.4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 90
+indent-width = 4
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+
+[tool.mypy]
+files = "src/**/*.py"
+show_error_codes = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+warn_return_any = true
+warn_unused_configs = true
+# disable_error_code = "misc"

vulnsig-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vulnsig-1.0.0/src/vulnsig/__init__.py

@@ -0,0 +1,3 @@
+from .render import render_glyph
+
+__all__ = ['render_glyph']

vulnsig-1.0.0/src/vulnsig/color.py

@@ -0,0 +1,28 @@
+from .types import HueResult
+
+
+def score_to_hue(score: float) -> HueResult:
+    w = max(0.0, min(10.0, score)) / 10.0
+
+    # Light Yellow (low) → Orange (mid) → Dark Red (high)
+    #   0 = light yellow  hsl(55, 95%, 55%)
+    #   5 = orange         hsl(25, 95%, 53%)
+    #  10 = dark red       hsl(0, 80%, 28%)
+    if w <= 0.5:
+        # light yellow → orange: hue 55 → 25
+        hue = 55 - (w / 0.5) * 30
+    else:
+        # orange → dark red: hue 25 → 0
+        hue = 25 - ((w - 0.5) / 0.5) * 25
+
+    sat = 85 + (1 - w) * 10  # 95% at low → 85% at high
+
+    # Lightness multiplier: asymmetric — subtle brightening for low scores,
+    # aggressive darkening for high scores (8-10 distinguishability)
+    #   score 0: 1.15, score 5: 1.0, score 10: 0.55
+    if w <= 0.5:
+        light = 1.0 + (0.5 - w) * 0.3  # low end:  1.0 → 1.15
+    else:
+        light = 1.0 - (w - 0.5) * 0.9  # high end: 1.0 → 0.55
+
+    return HueResult(hue=hue, sat=sat, light=light)

vulnsig-1.0.0/src/vulnsig/geometry.py

@@ -0,0 +1,86 @@
+import math
+from typing import NamedTuple
+
+_DEG2RAD = math.pi / 180
+
+
+class Cut(NamedTuple):
+    start_deg: float
+    end_deg: float
+
+
+def arc_path(
+    cx: float,
+    cy: float,
+    inner_r: float,
+    outer_r: float,
+    start_deg: float,
+    end_deg: float,
+) -> str:
+    s = start_deg * _DEG2RAD
+    e = end_deg * _DEG2RAD
+    la = 1 if (end_deg - start_deg) > 180 else 0
+    osx = cx + math.cos(s) * outer_r
+    osy = cy + math.sin(s) * outer_r
+    oex = cx + math.cos(e) * outer_r
+    oey = cy + math.sin(e) * outer_r
+    iex = cx + math.cos(e) * inner_r
+    iey = cy + math.sin(e) * inner_r
+    isx = cx + math.cos(s) * inner_r
+    isy = cy + math.sin(s) * inner_r
+    return (
+        f'M{osx},{osy} A{outer_r},{outer_r} 0 {la},1 {oex},{oey} '
+        f'L{iex},{iey} A{inner_r},{inner_r} 0 {la},0 {isx},{isy} Z'
+    )
+
+
+def star_path(
+    cx: float,
+    cy: float,
+    points: int,
+    outer_r: float,
+    inner_r: float,
+) -> str:
+    d = ''
+    for i in range(points):
+        oa = (math.pi * 2 * i) / points - math.pi / 2
+        ia = (math.pi * 2 * (i + 0.5)) / points - math.pi / 2
+        ox = cx + math.cos(oa) * outer_r
+        oy = cy + math.sin(oa) * outer_r
+        ix = cx + math.cos(ia) * inner_r
+        iy = cy + math.sin(ia) * inner_r
+        if i == 0:
+            d += f'M{ox},{oy}'
+        else:
+            d += f'L{ox},{oy}'
+        d += f'L{ix},{iy}'
+    return d + 'Z'
+
+
+def radial_cuts(
+    start_deg: float,
+    end_deg: float,
+    cut_width: float,
+    gap_deg: float,
+) -> list[Cut]:
+    cuts: list[Cut] = []
+    sector_span = end_deg - start_deg
+    step = cut_width + gap_deg
+    # Number of visible segments = num_cuts + 1, each gap_deg wide.
+    # Total = num_cuts * cut_width + (num_cuts + 1) * gap_deg = sector_span
+    # Solve: num_cuts = floor((sector_span - gap_deg) / step)
+    num_cuts = int((sector_span - gap_deg) / step)
+    pattern_span = num_cuts * cut_width + (num_cuts + 1) * gap_deg
+    offset = (sector_span - pattern_span) / 2
+    for i in range(num_cuts):
+        cut_start = start_deg + offset + (i + 1) * gap_deg + i * cut_width
+        cuts.append(Cut(start_deg=cut_start, end_deg=cut_start + cut_width))
+    return cuts
+
+
+def ring_fill(magnitude: float, hue: float, sat: float, light: float = 1.0) -> str:
+    if magnitude <= 0.01:
+        return f'hsla({hue}, {sat * 0.1}%, {12 * light}%, 0.9)'
+    if magnitude <= 0.5:
+        return f'hsla({hue}, {sat * 0.5}%, {35 * light}%, 0.92)'
+    return f'hsla({hue}, {sat * 0.9}%, {58 * light}%, 0.95)'

vulnsig-1.0.0/src/vulnsig/parse.py

@@ -0,0 +1,50 @@
+from .types import MetricKey, ParsedMetrics
+
+METRIC_DEFS: dict[MetricKey, dict[str, float]] = {
+    'AV': {'N': 1.0, 'A': 0.7, 'L': 0.4, 'P': 0.15},
+    'AC': {'L': 1.0, 'H': 0.4},
+    'AT': {'N': 1.0, 'P': 0.4},
+    'PR': {'N': 1.0, 'L': 0.6, 'H': 0.2},
+    'UI': {'N': 1.0, 'P': 0.6, 'A': 0.2, 'R': 0.2},  # R for CVSS 3.0/3.1
+    'VC': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'VI': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'VA': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'SC': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'SI': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'SA': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    # CVSS 3.0/3.1 metrics (C/I/A without V prefix, S for scope)
+    'C': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'I': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'A': {'H': 1.0, 'L': 0.5, 'N': 0.0},
+    'S': {'C': 1.0, 'U': 0.0},  # Scope: Changed or Unchanged
+}
+
+
+def parse_cvss(vector: str) -> ParsedMetrics:
+    m: dict[str, str] = {}
+    for part in vector.split('/'):
+        if ':' in part:
+            key, val = part.split(':', 1)
+            if key in METRIC_DEFS:
+                m[key] = val
+    return m  # type: ignore[return-value]
+
+
+def detect_cvss_version(vector: str) -> str:
+    if vector.startswith('CVSS:3.1/'):
+        return '3.1'
+    elif vector.startswith('CVSS:3.0/'):
+        return '3.0'
+    elif vector.startswith('CVSS:4.0/'):
+        return '4.0'
+    raise ValueError(
+        "Unsupported CVSS version. Vector must start with 'CVSS:3.0/', 'CVSS:3.1/', or 'CVSS:4.0/'"
+    )
+
+
+def is_version3(version: str) -> bool:
+    return version in ('3.0', '3.1')
+
+
+def get_severity(metrics: ParsedMetrics, key: MetricKey) -> float:
+    return METRIC_DEFS[key][metrics[key]]

vulnsig-1.0.0/src/vulnsig/render.py

@@ -0,0 +1,229 @@
+import ctypes
+import math
+from typing import NamedTuple
+
+from .color import score_to_hue
+from .geometry import arc_path, radial_cuts, ring_fill, star_path
+from .parse import detect_cvss_version, get_severity, is_version3, parse_cvss
+from .score import calculate_score
+
+
+class Sector(NamedTuple):
+    key: str
+    s: float  # start angle (degrees)
+    e: float  # end angle (degrees)
+    vuln: float
+    sub: float
+
+
+def render_glyph(vector: str, score: float | None = None, size: int = 120) -> str:
+    metrics = parse_cvss(vector)
+    version = detect_cvss_version(vector)
+
+    # Score precedence: explicit → auto-calculate
+    if score is None:
+        score = calculate_score(vector)
+
+    hue_result = score_to_hue(score)
+    hue = hue_result['hue']
+    sat = hue_result['sat']
+    light = hue_result['light']
+
+    # Metric severities - handle CVSS 3.0, 3.1, and 4.0
+    ac = get_severity(metrics, 'AC')
+
+    # For CVSS 3.0/3.1, AT doesn't exist, so always treat as solid (AT:N)
+    at = 1.0 if is_version3(version) else get_severity(metrics, 'AT')
+
+    # For CVSS 3.0/3.1, use C/I/A instead of VC/VI/VA
+    vc = (
+        get_severity(metrics, 'C')
+        if is_version3(version)
+        else get_severity(metrics, 'VC')
+    )
+    vi = (
+        get_severity(metrics, 'I')
+        if is_version3(version)
+        else get_severity(metrics, 'VI')
+    )
+    va = (
+        get_severity(metrics, 'A')
+        if is_version3(version)
+        else get_severity(metrics, 'VA')
+    )
+
+    # For CVSS 3.0/3.1, if S:C (Changed), both bands mirror C/I/A. If S:U (Unchanged), no split.
+    if is_version3(version):
+        scope_changed = get_severity(metrics, 'S') > 0.5  # S:C = 1.0, S:U = 0.0
+        if scope_changed:
+            # Split band: both bands mirror C/I/A
+            sc, si, sa = vc, vi, va
+        else:
+            # No split
+            sc = si = sa = 0.0
+    else:
+        # CVSS 4.0: use SC/SI/SA directly
+        sc = get_severity(metrics, 'SC')
+        si = get_severity(metrics, 'SI')
+        sa = get_severity(metrics, 'SA')
+
+    has_any_sub = sc > 0 or si > 0 or sa > 0
+    at_present = at < 0.5
+
+    cx = cy = 60.0
+    petal_count = {'N': 8, 'A': 6, 'L': 4, 'P': 3}.get(metrics.get('AV', ''), 8)
+
+    # Geometry constants
+    ring_width = 4.375
+    ring_gap = 1.5
+    outer_r = 44.0
+    hue_ring_r = outer_r + ring_gap + ring_width / 2
+
+    sub_inner_r = outer_r - ring_width
+    vuln_outer_r = sub_inner_r - ring_gap
+    vuln_inner_r = vuln_outer_r - ring_width
+    inner_r = vuln_inner_r
+
+    gap_deg = 3.0
+    cut_gap_deg = 4.0
+    cut_width_deg = 3.0
+
+    star_outer_r = inner_r - 2
+    star_inner_r = star_outer_r * (0.55 - ac * 0.35)
+
+    # PR stroke
+    pr_raw = metrics.get('PR', '')
+    pr_stroke_width = 3.2 if pr_raw == 'H' else (1.0 if pr_raw == 'L' else 0.0)
+
+    # UI spikes/bumps
+    ui_raw = metrics.get('UI', '')
+    spike_base = hue_ring_r + ring_width / 2 - 0.5
+
+    # Star fill — match the outer hue ring color
+    sf_sat = sat
+    sf_light = 52 * light
+    sf_alpha = 0.85
+
+    bg_color = f'hsl({hue}, 4%, 5%)'
+
+    # Deterministic gradient ID from vector hash
+    grad_id = 'sg-' + _simple_hash(vector)
+
+    # Sectors
+    sectors = [
+        Sector('C', s=-150 + gap_deg / 2, e=-30 - gap_deg / 2, vuln=vc, sub=sc),
+        Sector('I', s=-30 + gap_deg / 2, e=90 - gap_deg / 2, vuln=vi, sub=si),
+        Sector('A', s=90 + gap_deg / 2, e=210 - gap_deg / 2, vuln=va, sub=sa),
+    ]
+
+    parts: list[str] = []
+
+    # Defs
+    parts.append(f'<defs><radialGradient id="{grad_id}" cx="50%" cy="50%" r="50%">')
+    parts.append(
+        f'<stop offset="0%" stop-color="hsla({hue}, {sf_sat * 1.1}%, {sf_light + 6}%, {min(1.0, sf_alpha + 0.1)})"/>'
+    )
+    parts.append(
+        f'<stop offset="100%" stop-color="hsla({hue}, {sf_sat}%, {sf_light}%, {sf_alpha})"/>'
+    )
+    parts.append('</radialGradient></defs>')
+
+    # Z-order 1: UI:N Spikes
+    if ui_raw == 'N':
+        for i in range(petal_count):
+            a = (math.pi * 2 * i) / petal_count - math.pi / 2
+            x1 = cx + math.cos(a) * spike_base
+            y1 = cy + math.sin(a) * spike_base
+            x2 = cx + math.cos(a) * (spike_base + 3.4)
+            y2 = cy + math.sin(a) * (spike_base + 3.4)
+            parts.append(
+                f'<line x1="{x1}" y1="{y1}" x2="{x2}" y2="{y2}" '
+                f'stroke="hsl({hue}, {sat}%, {52 * light}%)" stroke-width="3.0" stroke-linecap="round"/>'
+            )
+
+    # Z-order 2: UI:P Bumps
+    if ui_raw == 'P':
+        bump_r = 4.6
+        for i in range(petal_count):
+            a = (math.pi * 2 * i) / petal_count - math.pi / 2
+            bx = cx + math.cos(a) * spike_base
+            by = cy + math.sin(a) * spike_base
+            perp_l = a - math.pi / 2
+            perp_r = a + math.pi / 2
+            x1 = bx + math.cos(perp_l) * bump_r
+            y1 = by + math.sin(perp_l) * bump_r
+            x2 = bx + math.cos(perp_r) * bump_r
+            y2 = by + math.sin(perp_r) * bump_r
+            parts.append(
+                f'<path d="M{x1},{y1} A{bump_r},{bump_r} 0 0,1 {x2},{y2} Z" '
+                f'fill="hsl({hue}, {sat}%, {52 * light}%)"/>'
+            )
+
+    # Z-order 3: Background circle
+    parts.append(f'<circle cx="{cx}" cy="{cy}" r="{inner_r}" fill="{bg_color}"/>')
+
+    # Z-order 4: Star fill
+    star_d = star_path(cx, cy, petal_count, star_outer_r, star_inner_r)
+    parts.append(f'<path d="{star_d}" fill="url(#{grad_id})" stroke="none"/>')
+
+    # Z-order 5: Star stroke (PR:N = no stroke)
+    if pr_stroke_width > 0:
+        parts.append(
+            f'<path d="{star_d}" fill="none" stroke="hsl({hue}, {sat}%, {72 * light}%)" '
+            f'stroke-width="{pr_stroke_width}" stroke-linejoin="round"/>'
+        )
+
+    # Z-order 6 & 7: CIA ring sectors
+    for sec in sectors:
+        # Vuln band (inner)
+        vuln_band_outer = vuln_outer_r if has_any_sub else outer_r
+        parts.append(
+            f'<path d="{arc_path(cx, cy, vuln_inner_r, vuln_band_outer, sec.s, sec.e)}" '
+            f'fill="{ring_fill(sec.vuln, hue, sat, light)}"/>'
+        )
+
+        # Sub band (outer) — only when split
+        if has_any_sub:
+            parts.append(
+                f'<path d="{arc_path(cx, cy, sub_inner_r, outer_r, sec.s, sec.e)}" '
+                f'fill="{ring_fill(sec.sub, hue, sat, light)}"/>'
+            )
+
+    # Z-order 8: AT:P radial cuts
+    if at_present:
+        for sec in sectors:
+            cuts = radial_cuts(sec.s, sec.e, cut_width_deg, cut_gap_deg)
+            for cut in cuts:
+                parts.append(
+                    f'<path d="{arc_path(cx, cy, vuln_inner_r - 0.5, outer_r + 0.5, cut.start_deg, cut.end_deg)}" '
+                    f'fill="{bg_color}"/>'
+                )
+
+    # Z-order 9: Outer hue ring
+    parts.append(
+        f'<circle cx="{cx}" cy="{cy}" r="{hue_ring_r}" fill="none" '
+        f'stroke="hsl({hue}, {sat}%, {52 * light}%)" stroke-width="{ring_width}"/>'
+    )
+
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{size}" height="{size}" '
+        f'viewBox="0 0 120 120" style="overflow:visible">{"".join(parts)}</svg>'
+    )
+
+
+def _simple_hash(s: str) -> str:
+    h = 0
+    for ch in s:
+        h = ctypes.c_int32((h << 5) - h + ord(ch)).value
+    return _to_base36(abs(h))
+
+
+def _to_base36(n: int) -> str:
+    if n == 0:
+        return '0'
+    digits: list[str] = []
+    alphabet = '0123456789abcdefghijklmnopqrstuvwxyz'
+    while n:
+        digits.append(alphabet[n % 36])
+        n //= 36
+    return ''.join(reversed(digits))

vulnsig-1.0.0/src/vulnsig/score.py

@@ -0,0 +1,13 @@
+from cvss import CVSS3, CVSS4  # type: ignore
+
+from .parse import detect_cvss_version
+
+
+def calculate_score(vector: str) -> float:
+    version = detect_cvss_version(vector)
+    if version in ('3.0', '3.1'):
+        c = CVSS3(vector)
+        return float(c.base_score)
+    # CVSS 4.0 (validated by detect_cvss_version)
+    c = CVSS4(vector)
+    return float(c.base_score)

vulnsig-1.0.0/src/vulnsig/types.py

@@ -0,0 +1,46 @@
+from typing import Literal, TypedDict
+
+MetricKey = Literal[
+    'AV',
+    'AC',
+    'AT',
+    'PR',
+    'UI',
+    'VC',
+    'VI',
+    'VA',
+    'SC',
+    'SI',
+    'SA',
+    'C',
+    'I',
+    'A',
+    'S',
+]
+
+
+class ParsedMetrics(TypedDict, total=False):
+    # CVSS 4.0 + 3.x shared
+    AV: Literal['N', 'A', 'L', 'P']
+    AC: Literal['L', 'H']
+    PR: Literal['N', 'L', 'H']
+    UI: Literal['N', 'P', 'A', 'R']  # R for CVSS 3.0/3.1
+    # CVSS 4.0 only
+    AT: Literal['N', 'P']
+    VC: Literal['H', 'L', 'N']
+    VI: Literal['H', 'L', 'N']
+    VA: Literal['H', 'L', 'N']
+    SC: Literal['H', 'L', 'N']
+    SI: Literal['H', 'L', 'N']
+    SA: Literal['H', 'L', 'N']
+    # CVSS 3.x only
+    C: Literal['H', 'L', 'N']
+    I: Literal['H', 'L', 'N']  # noqa: E741
+    A: Literal['H', 'L', 'N']
+    S: Literal['C', 'U']  # Scope: Changed or Unchanged
+
+
+class HueResult(TypedDict):
+    hue: float
+    sat: float
+    light: float  # multiplier: >1 lighter (low scores), <1 darker (high scores)

vulnsig-1.0.0/src/vulnsig.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: vulnsig
+Version: 1.0.0
+Summary: Render CVSS vulnerability vectors as expressive SVG glyphs
+License-Expression: MIT
+Project-URL: Homepage, https://vulnsig.io
+Project-URL: Repository, https://github.com/vulnsig/vulnsig-py
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cvss==3.6
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: ruff==0.15.0; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: nox==2025.11.12; extra == "dev"
+Requires-Dist: build==1.4.0; extra == "dev"
+
+# vulnsig-py
+
+Render CVSS vulnerability vectors as expressive SVG glyphs. Each glyph encodes all base metrics visually with shape, color, rings, and texture, so vulnerabilities are recognizable at a glance.
+
+Supports CVSS 4.0, 3.1, and 3.0.
+
+## Install
+
+```bash
+pip install vulnsig
+```
+
+## Usage
+
+```python
+from vulnsig import render_glyph
+
+svg = render_glyph("CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H")
+
+# override the score (e.g. if you already have it)
+svg = render_glyph("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H", score=10.0)
+
+# control rendered size in pixels (default 120)
+svg = render_glyph("CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N", size=64)
+```
+
+`render_glyph` returns an SVG string ready to embed in HTML or write to a file.
+
+## Examples
+
+### CVSS 4.0
+
+| Glyph | Name | Vector | Score |
+|:-----:|------|--------|------:|
+| <img src="assets/log4shell.svg" width="80"> | Log4Shell | `AV:N AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:H SI:H SA:H` | 10.0 |
+| <img src="assets/eternalblue.svg" width="80"> | EternalBlue | `AV:N AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:N SI:N SA:N` | 9.3 |
+| <img src="assets/heartbleed.svg" width="80"> | Heartbleed | `AV:N AC:L AT:N PR:N UI:N VC:H VI:N VA:N SC:L SI:N SA:N` | 8.7 |
+| <img src="assets/spectre.svg" width="80"> | Spectre | `AV:L AC:H AT:P PR:L UI:N VC:H VI:N VA:N SC:H SI:N SA:N` | 5.6 |
+| <img src="assets/xss-stored.svg" width="80"> | XSS Stored | `AV:N AC:L AT:N PR:L UI:P VC:L VI:L VA:N SC:N SI:N SA:N` | 5.1 |
+| <img src="assets/usb-physical.svg" width="80"> | USB Drop | `AV:P AC:L AT:N PR:N UI:N VC:H VI:H VA:H SC:N SI:N SA:N` | 7.3 |
+
+### CVSS 3.x
+
+| Glyph | Name | Vector | Score |
+|:-----:|------|--------|------:|
+| <img src="assets/log4shell-31.svg" width="80"> | Log4Shell | `AV:N AC:L PR:N UI:N S:C C:H I:H A:H` | 10.0 |
+| <img src="assets/xss-reflected-31.svg" width="80"> | XSS Reflected | `AV:N AC:L PR:N UI:R S:C C:L I:L A:N` | 6.1 |
+
+## Visual encoding
+
+Each metric maps to a distinct visual channel:
+
+| Metric | Channel |
+|--------|---------|
+| Score | Hue — yellow (low) → orange → dark red (high) |
+| AV | Star points — N=8, A=6, L=4, P=3 |
+| AC | Star pointiness — L=sharp, H=blunt |
+| AT | Ring segmentation — N=solid, P=cut pattern |
+| PR | Star outline — N=none, L=thin, H=thick |
+| UI | Perimeter — N=spikes, P=bumps, A=clean |
+| VC/VI/VA | Inner ring brightness per sector |
+| SC/SI/SA | Outer ring band (split when any > 0) |
+
+## Requirements
+
+Python 3.10+

vulnsig-1.0.0/src/vulnsig.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/vulnsig/__init__.py
+src/vulnsig/color.py
+src/vulnsig/geometry.py
+src/vulnsig/parse.py
+src/vulnsig/render.py
+src/vulnsig/score.py
+src/vulnsig/types.py
+src/vulnsig.egg-info/PKG-INFO
+src/vulnsig.egg-info/SOURCES.txt
+src/vulnsig.egg-info/dependency_links.txt
+src/vulnsig.egg-info/requires.txt
+src/vulnsig.egg-info/top_level.txt
+tests/test_vulnsig.py

vulnsig-1.0.0/src/vulnsig.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vulnsig-1.0.0/src/vulnsig.egg-info/requires.txt

@@ -0,0 +1,8 @@
+cvss==3.6
+
+[dev]
+pytest==9.0.2
+ruff==0.15.0
+mypy==1.19.1
+nox==2025.11.12
+build==1.4.0

vulnsig-1.0.0/src/vulnsig.egg-info/top_level.txt

@@ -0,0 +1 @@
+vulnsig

vulnsig-1.0.0/tests/test_vulnsig.py

@@ -0,0 +1,213 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from vulnsig import render_glyph
+from vulnsig.color import score_to_hue
+from vulnsig.parse import detect_cvss_version, is_version3, parse_cvss
+from vulnsig.score import calculate_score
+
+LOG4SHELL = 'CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H'
+
+# CVSS 3.1 test vectors
+CVSS31_LOG4SHELL = 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H'
+CVSS31_HEARTBLEED = 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N'
+CVSS31_DIRTY_COW = 'CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:N'
+CVSS31_XSS = 'CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N'
+
+# CVSS 3.0 test vectors (same format as 3.1)
+CVSS30_LOG4SHELL = 'CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H'
+CVSS30_HEARTBLEED = 'CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N'
+CVSS30_XSS = 'CVSS:3.0/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N'
+
+_TEST_VECTORS_PATH = Path(__file__).parent.parent / 'spec' / 'test-vectors.json'
+with _TEST_VECTORS_PATH.open() as _f:
+    TEST_VECTORS = json.load(_f)
+
+
+# ---------------------------------------------------------------------------
+# parse_cvss
+# ---------------------------------------------------------------------------
+
+
+class TestParseCVSS:
+    def test_parses_full_vector(self):
+        m = parse_cvss(LOG4SHELL)
+        assert m['AV'] == 'N'
+        assert m['AC'] == 'L'
+        assert m['SC'] == 'H'
+
+    def test_handles_missing_optional_metrics(self):
+        m = parse_cvss('CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H')
+        assert m['AV'] == 'N'
+        assert m.get('SC') is None
+
+    def test_parses_cvss31_vector(self):
+        m = parse_cvss(CVSS31_LOG4SHELL)
+        assert m['AV'] == 'N'
+        assert m['AC'] == 'L'
+        assert m['C'] == 'H'
+        assert m['I'] == 'H'
+        assert m['A'] == 'H'
+        assert m['S'] == 'C'
+
+    def test_parses_cvss30_vector(self):
+        m = parse_cvss(CVSS30_LOG4SHELL)
+        assert m['AV'] == 'N'
+        assert m['AC'] == 'L'
+        assert m['C'] == 'H'
+        assert m['I'] == 'H'
+        assert m['A'] == 'H'
+        assert m['S'] == 'C'
+
+
+# ---------------------------------------------------------------------------
+# detect_cvss_version
+# ---------------------------------------------------------------------------
+
+
+class TestDetectCVSSVersion:
+    def test_detects_30(self):
+        assert detect_cvss_version(CVSS30_LOG4SHELL) == '3.0'
+
+    def test_detects_31(self):
+        assert detect_cvss_version(CVSS31_LOG4SHELL) == '3.1'
+
+    def test_detects_40(self):
+        assert detect_cvss_version(LOG4SHELL) == '4.0'
+
+    def test_raises_for_unsupported_version(self):
+        with pytest.raises(ValueError, match='Unsupported CVSS version'):
+            detect_cvss_version('CVSS:2.0/AV:N/AC:L/Au:N/C:P/I:P/A:P')
+
+    def test_raises_for_missing_prefix(self):
+        with pytest.raises(ValueError, match='Unsupported CVSS version'):
+            detect_cvss_version('AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H')
+
+
+# ---------------------------------------------------------------------------
+# is_version3
+# ---------------------------------------------------------------------------
+
+
+class TestIsVersion3:
+    def test_true_for_30(self):
+        assert is_version3('3.0') is True
+
+    def test_true_for_31(self):
+        assert is_version3('3.1') is True
+
+    def test_false_for_40(self):
+        assert is_version3('4.0') is False
+
+
+# ---------------------------------------------------------------------------
+# score_to_hue
+# ---------------------------------------------------------------------------
+
+
+class TestScoreToHue:
+    def test_yellow_for_score_0(self):
+        assert score_to_hue(0)['hue'] == 55
+
+    def test_dark_red_for_score_10(self):
+        assert score_to_hue(10)['hue'] == 0
+
+    def test_hue_decreases_with_score(self):
+        assert score_to_hue(0)['hue'] > score_to_hue(10)['hue']
+
+
+# ---------------------------------------------------------------------------
+# calculate_score
+# ---------------------------------------------------------------------------
+
+
+class TestCalculateScore:
+    def test_log4shell_is_10(self):
+        assert calculate_score(LOG4SHELL) == 10.0
+
+    def test_invalid_vector_returns_5(self):
+        with pytest.raises(ValueError):
+            calculate_score('garbage')
+
+    def test_cvss31_log4shell(self):
+        assert calculate_score(CVSS31_LOG4SHELL) == 10.0
+
+    def test_cvss31_heartbleed(self):
+        assert calculate_score(CVSS31_HEARTBLEED) == 7.5
+
+    def test_cvss31_dirty_cow(self):
+        assert calculate_score(CVSS31_DIRTY_COW) == 7.1
+
+    def test_cvss31_xss(self):
+        assert calculate_score(CVSS31_XSS) == 6.1
+
+    def test_cvss30_log4shell(self):
+        assert calculate_score(CVSS30_LOG4SHELL) == 10.0
+
+    def test_cvss30_heartbleed(self):
+        assert calculate_score(CVSS30_HEARTBLEED) == 7.5
+
+    def test_cvss30_xss(self):
+        assert calculate_score(CVSS30_XSS) == 6.1
+
+
+# ---------------------------------------------------------------------------
+# render_glyph
+# ---------------------------------------------------------------------------
+
+
+class TestRenderGlyph:
+    def test_returns_valid_svg(self):
+        svg = render_glyph(LOG4SHELL, score=10)
+        assert svg.startswith('<svg ')
+        assert svg.endswith('</svg>')
+
+    def test_respects_size_parameter(self):
+        svg = render_glyph(LOG4SHELL, score=10, size=64)
+        assert 'width="64"' in svg
+        assert 'height="64"' in svg
+
+    def test_renders_all_test_vectors(self):
+        for tv in TEST_VECTORS:
+            svg = render_glyph(tv['vector'], score=tv['score'])
+            assert svg.startswith('<svg ')
+            assert svg.endswith('</svg>')
+
+    def test_renders_cvss31_vectors(self):
+        for vector in [CVSS31_LOG4SHELL, CVSS31_HEARTBLEED, CVSS31_DIRTY_COW, CVSS31_XSS]:
+            svg = render_glyph(vector)
+            assert svg.startswith('<svg ')
+            assert svg.endswith('</svg>')
+
+    def test_cvss31_scope_changed_split_band(self):
+        svg = render_glyph(CVSS31_LOG4SHELL)
+        assert '<svg' in svg
+        assert '</svg>' in svg
+
+    def test_cvss31_scope_unchanged_no_split(self):
+        svg = render_glyph(CVSS31_HEARTBLEED)
+        assert '<svg' in svg
+        assert '</svg>' in svg
+
+    def test_cvss31_ui_r_clean_perimeter(self):
+        svg = render_glyph(CVSS31_XSS)
+        assert '<svg' in svg
+        assert '</svg>' in svg
+
+    def test_renders_cvss30_vectors(self):
+        for vector in [CVSS30_LOG4SHELL, CVSS30_HEARTBLEED, CVSS30_XSS]:
+            svg = render_glyph(vector)
+            assert svg.startswith('<svg ')
+            assert svg.endswith('</svg>')
+
+    def test_cvss30_scope_changed_split_band(self):
+        svg = render_glyph(CVSS30_LOG4SHELL)
+        assert '<svg' in svg
+        assert '</svg>' in svg
+
+    def test_cvss30_scope_unchanged_no_split(self):
+        svg = render_glyph(CVSS30_HEARTBLEED)
+        assert '<svg' in svg
+        assert '</svg>' in svg