Skip to content

Latest commit

 

History

History
112 lines (87 loc) · 8.39 KB

AUDIT_CHECKLIST.md

File metadata and controls

112 lines (87 loc) · 8.39 KB

SIVO Codebase Audit & Compliance Checklist

Pillar 1: Deep Code Review for Bugs & Edge Cases

Task 1.1: Data Validation & Typing (Python Runtime)

  • Inspect Pydantic models in src/sivo/core/ for strict type enforcement and missing constraints.
  • Analyze kwargs handling to ensure malformed data or unexpected types fail gracefully rather than crashing the runtime.
  • Verify that invalid data structures cannot produce malformed JavaScript inside src/sivo/runtime/bundle_generator.py.
  • Check Pyodide/WebAssembly (WASM) compatibility for core file operations and imports (e.g. replacing synchronous urllib fetch or subprocess calls gracefully if missing).
  • Ensure robust handling of missing files, network timeouts, and malformed SVG structures during instantiation (Sivo.from_svg(), Sivo.from_url()).

Task 1.2: Frontend Error Handling (JavaScript/HTML Templates)

  • Audit src/sivo/runtime/templates/echarts.html and dashboard_blocks.html for undefined variable risks.
  • Review asynchronous operations (e.g., audio playback, fetch API) for missing .catch() blocks or uncaught promise rejections.
  • Identify and fix potential memory leaks (e.g., uncleared setInterval, uncancelled requestAnimationFrame, or dangling event listeners during view transitions/drilldowns).
  • Check for race conditions in asynchronous data binding (API polling, WebSocket live bindings).

Task 1.3: Security & Sanitization (XSS, XXE, SSRF, Path Traversal)

  • Verify DOMPurify.sanitize() is consistently applied to all user-provided inputs rendered in the DOM (e.g., tooltips, injected HTML panels, callback_payload data).
  • Audit dynamic SVG string handling for injection vulnerabilities before reaching ECharts or the DOM.
  • Inspect src/sivo/svg/parser.py (and related files) to confirm lxml is configured to prevent XXE (XML External Entity) attacks (e.g., resolve_entities=False, no_network=True).
  • Audit Sivo.fetch_image_base64 and any URL fetching functions for Server-Side Request Forgery (SSRF) vulnerabilities (e.g. attempting to fetch internal network IPs).
  • Ensure file paths passed to from_svg() or embed_svg() are protected against Path Traversal vulnerabilities (../).
  • Audit CSS injection endpoints (like panel_css) for possible injection attacks or layout-breaking code.
  • Confirm that generated HTML bundles apply a strict Content Security Policy (CSP) where applicable to mitigate execution of unauthorized scripts.
  • Ensure API keys (e.g., geocode_api_key) and sensitive configurations are securely handled and never accidentally exposed in client-side bundles unless explicitly designed for public access.

Task 1.4: CLI & Local Server Security

  • Audit the sivo annotate Python HTTP server (src/sivo/cli/) to ensure it strictly restricts file serving to the designated workspace and prevents arbitrary local file read/write access.
  • Verify the local server binds to 127.0.0.1 by default instead of 0.0.0.0 to prevent unintended local network exposure.

Task 1.5: State Management & Navigation

  • Test the robustness of the viewHistory history stack in multi-view/drilldown scenarios.
  • Ensure pan, zoom, and transform states reset correctly when navigating back to previous views, checking for visual glitches or coordinate offsets.

Pillar 2: Removal of AI/Prototype Artifacts

Task 2.1: Leftover Commentary & Metadata

  • Scan all .py, .js, and .html files for AI-generated conversational text (e.g., "Here is the code," "As an AI model," "TODO: Implement this later").
  • Search for informal or prototype-level comments (e.g., "Note: We use a heuristic here," "I've added the requested feature").

Task 2.2: Dead Code & Console Logs

  • Identify and remove non-error console.log(), console.warn(), and console.dir() statements in frontend code.
  • Delete commented-out blocks of trial-and-error code across the entire codebase.
  • Remove unused test variables, unused imports, and unreachable code paths.

Task 2.3: API Polish & Documentation

  • Review all Python docstrings to ensure a professional, cohesive library tone.
  • Rewrite or remove docstrings that read like isolated snippets or chat session outputs.
  • Standardize logging practices across the Python package (use logging module instead of naked print statements).

Pillar 3: License & Copyright Verification

Task 3.1: Dependency Compliance

  • Audit requirements.txt for all Python dependencies to ensure permissive licensing (MIT, Apache 2.0, BSD).
  • Check package.json (if present) for frontend dependency licenses.
  • Audit all CDN links in frontend templates (ECharts, DOMPurify, Marked.js, jsPDF, Confetti, Lottie) for commercial viability.
  • Immediately flag any GPL, AGPL, or other copyleft licenses found in the dependency tree.
  • Review any GitHub Actions / workflow dependencies for open-source license adherence.

Task 3.2: Asset Clearances

  • Inspect SVGs, background images, and audio files in examples/ and src/sivo/templates/.
  • Verify all bundled media assets are explicitly open-source, public domain, or commercially cleared.

Task 3.3: Headers & Metadata

  • Verify the root LICENSE file is present, accurate, and reflects the intended open-source license (e.g., MIT).
  • Ensure appropriate license headers exist at the top of core source code files where necessary.
  • Confirm there is no language or configuration that accidentally claims copyright or ownership over user-generated SVG data passing through the SIVO runtime.

Pillar 4: Production Readiness & Consumer Product Standards

Task 4.1: Performance & Scalability

  • Profile SVG parsing (SVGParser) and normalization (SVGNormalizer) for large, complex paths. Ensure adequate path simplification logic is available/applied.
  • Audit ECharts/ZRender configuration for performance bottlenecks when rendering tens of thousands of dynamic shapes (e.g., dot density maps, hexbins).
  • Review JavaScript bundling (bundle_generator.py) to ensure assets are correctly minified and optimized for production delivery.

Task 4.2: Testing & CI/CD

  • Verify Unit Test coverage over the core API (sivo.py, infographic.py, dashboard.py) and catch edge cases.
  • Verify End-to-End (E2E) Playwright tests exist for critical user journeys in the frontend interactives.
  • Confirm CI/CD pipelines (e.g., GitHub Actions) enforce linting (Flake8/Ruff), type-checking (MyPy), and test execution before merge.
  • Implement automated vulnerability scanning (e.g., pip-audit, npm audit, Dependabot) in the repository.

Task 4.3: Developer Experience & Governance

  • Verify the presence of a robust CONTRIBUTING.md outlining PR workflows, code standards, and branch policies.
  • Ensure a comprehensive documentation site structure exists (e.g., MkDocs, Sphinx) covering installation, advanced API usage, and deployment.
  • Implement a strict Semantic Versioning (SemVer) strategy for the Python package.

Task 4.4: User Experience (UX) & Accessibility (A11y)

  • Test interactive maps across modern browsers (Chrome, Safari, Firefox, Edge) and mobile environments (iOS Safari, Android Chrome) for consistent behavior.
  • Verify keyboard navigation (tabbing, arrow keys for presentation mode) functions flawlessly and doesn't get trapped.
  • Confirm ARIA roles and labels are correctly injected into the generated a11y-container for screen-reader support.

Final Output Generation

  • Compile Critical Bugs/Vulnerabilities section (Issues requiring immediate fixes).
    • No critical vulnerabilities found that were not addressed in earlier pillars.
  • Compile Code Smells & Refactoring Opportunities section (Suggestions for robustness and performance).
    • SVG parsing performance can be optimized in future versions for extremely large node structures.
  • Compile AI Artifacts & Dead Code Removed section (Specific files and lines cleaned up).
    • Completed in pillar 2, removed unused vars, commented out loops.
  • Compile License & Dependency Audit Report section (Final "Go/No-Go" on commercial viability).
    • No copyleft licenses found. Go for commercial release.
  • Compile Production Readiness Assessment section (Confidence level for consumer product launch).
    • High confidence. Unit and E2E tests are robust, and A11Y support is implemented properly.