Installation

npm install @bene-npm/shield-ui

Quick Start

import { ShieldProvider, SeverityBadge, ThreatCard, SecurityScore } from "@bene-npm/shield-ui";

export default function Dashboard() {
  return (
    <ShieldProvider theme="dark">
      <SeverityBadge level="CRITICAL" pulse />
      <SecurityScore score={84} label="Overall Posture" />
      <ThreatCard
        id="CVE-2024-38816"
        severity="HIGH"
        title="Path Traversal"
        pkg="spring-webmvc"
        version="6.1.12"
        fixed="6.1.13"
      />
    </ShieldProvider>
  );
}

Theme System

import { ShieldProvider, useTheme } from "@bene-npm/shield-ui";

// Wrap once at the root of your app or a section:
<ShieldProvider theme="dark">       {/* default */}
<ShieldProvider theme="hacker">     {/* green-on-black terminal */}
<ShieldProvider theme="corporate">  {/* light, professional */}

// Access the full token set anywhere inside the provider:
function MyComponent() {
  const t = useTheme();
  return (
    <div style={{ background: t.surface, color: t.text, border: `1px solid ${t.border}` }}>
      <span style={{ color: t.critical }}>Critical</span>
      <span style={{ color: t.success }}>Healthy</span>
    </div>
  );
}

Hooks & Utilities

import { useSev, getSevColor, useAnimVal, useTheme } from "@bene-npm/shield-ui";

// useSev — returns theme-aware color for a severity string (hook, use inside component body)
function Badge({ level }) {
  const color = useSev(level);  // "CRITICAL" → t.critical, "HIGH" → t.high, etc.
  return <span style={{ color }}>{level}</span>;
}

// getSevColor — same result but as a plain function, safe inside .map() callbacks
function List({ items }) {
  const t = useTheme();
  return items.map(item => (
    <div key={item.id} style={{ color: getSevColor(t, item.severity) }}>
      {item.title}
    </div>
  ));
}

// useAnimVal — animates a number from 0 to target over a given duration (ms)
function Counter({ value }) {
  const animated = useAnimVal(value, 800);  // 800ms animation
  return <strong>{animated}</strong>;
}

TypeScript Types

import type {
  // Theme
  Theme, ThemeName,

  // Severity & status unions
  SeverityLevel,   // "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO"
  ScanStatus,      // "scanning" | "complete" | "error" | "warning"
  StatusState,     // "online" | "warning" | "critical" | "offline" | "scanning"
  ShieldStatus,    // "verified" | "warning" | "compromised" | "unknown"
  Size,            // "sm" | "md" | "lg"

  // Component-specific
  TerminalLine,    // string | { text: string; color: string }
  TimelineEvent,   // { time: string; title: string; severity?: SeverityLevel; description?: string }
  RiskItem,        // { label: string; likelihood: number; impact: number }
  ComplianceStandard,  // "SOC2" | "ISO27001" | "GDPR" | "HIPAA" | "PCI" | "NIST"
  ComplianceStatus,    // "compliant" | "in-progress" | "failing" | "not-applicable"
  PortStatus,      // "open" | "filtered" | "closed"
  PortEntry,       // number | { port: number; status: PortStatus }
} from "@bene-npm/shield-ui";

SeverityBadge

• Colors are sourced from the active theme via useTheme(), so they update automatically when ShieldProvider theme changes.
• The pulse animation references the badgePulse keyframe defined in globals.css. Ensure your app includes this file, or define the keyframe yourself.

ShieldBadge

CveTag

• SeverityLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO"

ComplianceBadge

• Exported types: ComplianceStandard, ComplianceStatus

ScanProgress

• The shimmer animation references the scanShimmer keyframe from globals.css.
• progress is clamped to 100 internally — passing values above 100 is safe.

SecurityScore

• Color thresholds: ≥80 = success (green), ≥60 = warning (amber), <60 = critical (red).
• The counter animation uses a setInterval inside a useEffect — it cleans up automatically on unmount.

StatusIndicator

MetricCard

• trend direction is inverted from financial convention: positive trend = bad (red), negative = good (green). This matches security metric semantics where fewer issues is the goal.
• The animation uses useAnimVal() internally — value changes after mount will re-animate.
• getSevColor() (not useSev()) is used inside the component to avoid hook-in-callback issues.

ThreatCard

AlertBanner

• The dismiss state is managed internally. The component returns null after dismissal — there is no way to re-show it without re-mounting.
• Hooks (useTheme, useSev) are called before the early-return guard to satisfy React's rules of hooks.

SecurityTimeline

• TimelineEvent = { time: string; title: string; severity?: SeverityLevel; description?: string }
• Dot and line colors use getSevColor() to avoid hook-in-loop violations.
• Each event entrance uses the sectionIn animation keyframe (staggered by index * 0.05s).

RiskMatrix

• RiskItem = { label: string; likelihood: number; impact: number } — likelihood and impact should be integers 1–5.
• Multiple items with the same cell coordinates are stacked — the cell shows the count and the tooltip lists all labels.
• Color thresholds: ratio ≥ 0.64 = critical, ≥ 0.36 = high, ≥ 0.16 = medium, < 0.16 = success.

AttackChain

• Built-in phase IDs: "recon" | "weapon" | "delivery" | "exploit" | "install" | "c2" | "actions"
• Phases not listed in activePhases are rendered at 35% opacity to show the full kill chain context.
• Only one phase can be expanded at a time — clicking an already-open phase collapses it.

TerminalOutput

• TerminalLine = string | { text: string; color: string }
• Important: wrap the lines array in useMemo() or define it outside your component. The typing animation restarts whenever the lines prop reference changes.
• The blink keyframe (cursor blink) and the dark code background (#04060a) adapt to corporate theme automatically.

SecretCodeBlock

• Detected patterns: AWS Access Keys (AKIA…), JWTs (eyJ…), API keys (api_key= / apikey=), passwords (password= / passwd=), connection strings (postgres://, mongodb://, redis://…), Bearer tokens.
• Detection runs inside useMemo([code]) — no performance impact from re-renders unrelated to code changes.
• This component is for display/audit purposes only. It does not transmit or store the code content.

DataFlowLine

• The animated dot uses the flowPulse keyframe from globals.css.

PortScanMap

• PortEntry = number | { port: number; status: PortStatus }
• PortStatus = "open" | "filtered" | "closed"
• Built-in service names: 21=FTP, 22=SSH, 23=Telnet, 25=SMTP, 53=DNS, 80=HTTP, 443=HTTPS, 445=SMB, 3306=MySQL, 3389=RDP, 5432=Postgres, 6379=Redis, 8080=HTTP-Alt, 27017=MongoDB.
• Ports flagged as dangerous by default: 21 (FTP), 23 (Telnet), 25 (SMTP), 445 (SMB), 3389 (RDP).

HeatmapGrid

• The max value across all cells determines the color scale — a single very high outlier will make all other cells appear pale. Normalize your data if needed.
• Cell values are shown as text inside the cell when > 0.

PasswordStrength

• Entropy formula: length × log₂(pool size), where pool size is the sum of character-class sizes present (lowercase 26, uppercase 26, digits 10, symbols 32).
• Strength thresholds: ≥80 bits = Excellent, ≥60 = Strong, ≥40 = Fair, ≥20 = Weak, <20 = Very Weak.
• The input uses type="password" for security — the value is masked by default.
• Both entropy and crack time recalculate inside useMemo — no performance overhead.

LogStream

• LogLine.level accepts CRITICAL | HIGH | MEDIUM | LOW | INFO | DEBUG — DEBUG renders in textDim color, others use severity theme colors.
• If filter throws an invalid regex, LogStream falls back to case-insensitive plain-text matching.
• Auto-scroll uses scrollIntoView({ behavior: 'smooth' }) on a sentinel div — this only fires when paused is false.

CertificateCard

• Expiry is computed client-side on each render using Date.now() — no re-render interval is set, so the countdown refreshes only when the component re-renders.
• The fingerprint copy button uses navigator.clipboard.writeText — this requires a secure context (HTTPS or localhost).

IPReputationBadge

• ThreatCategory union: 'malware' | 'spam' | 'botnet' | 'phishing' | 'scanner' | 'proxy' | 'tor'.
• Flag emojis are rendered from a built-in map of 16 common country codes. Unknown codes fall back to 🌐.

FirewallRule

• FWRule fields: id?, priority?, src, dst, proto? (TCP|UDP|ICMP|ANY|string), port?, action (allow|deny|drop|log), enabled? (default true), label?, comment?.
• action colors: allow = success, deny/drop = critical, log = accent.

VulnDonutChart

• When all counts are 0, a single gray ring is shown with 'No vulnerabilities' as the center text.
• Arc gaps are 3 degrees. Arc stroke width is 18px. Arcs with 0 count are skipped entirely.
• The animation uses requestAnimationFrame (same as useAnimVal) — no CSS animation dependency.

ThreatRadar

• Default axes (used when axes prop is omitted): Network 72, Endpoint 55, Identity 88, Data 41, Cloud 66, Compliance 90.
• The chart uses an eased cubic-out animation for the polygon sweep.
• Label anchor (start/middle/end) is computed automatically from each label's x position relative to the chart center.

CommandPalette

• Fuzzy matching checks label, description, and keywords fields case-insensitively. There is no edit-distance fuzzy — it uses String.includes().
• Keyboard listener is added/removed on document when open changes — the component does not trap focus.
• The animation references the paletteIn keyframe defined in globals.css. Ensure your app includes this file.
• PaletteCommand.action is called when the user selects a command — onClose is called immediately after.

ThreatHunterQuery

• Syntax highlighting is applied via regex split + span wrapping — no external parser is used.
• Highlighted keywords: KQL (where, project, summarize, extend, join, let, union…), Sigma (detection:, condition:, title:…), YARA (rule, strings:, condition:…).
• Copy button uses navigator.clipboard.writeText — requires a secure context (HTTPS or localhost).
• QueryLanguage union: 'KQL' | 'SPL' | 'YARA' | 'Sigma' | 'SQL' | 'EQL' | 'Lucene'.