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.