How furryr/csense works
Project type and purpose
• CSense is a single-page web application (pure front-end) that loads and executes CCW (scratch-like) scripts in a sandbox, analyzes them for security vulnerabilities, and displays results.
• No explicit “backend” folder: all networking is done client-side via API wrappers (src/api/ccwdata.js, src/api/vmapi.js).
File structure to find architectural components
Top-level folders and their roles:
• src/api/
– CCW chain data client (ccwdata.js)
– Virtual machine API client (vmapi.js)
• src/base/
– Core engine glue (Monaco editor integration, scene manager, global state)
• src/sandbox/
– Secure execution environment (TypeScript bridge + JS sandbox runner)
• src/scene/
– Individual UI “scenes” or pages (home, about, project, result overlays, etc.)
• src/overlay/
– Floating UI components (identity prompt, result window)
• src/util/
– Helpers (cookies, encryption, DOM injection, window helpers)
• src/asset/
– Static cert, other assets
Build tooling:
• script/*.mjs for bundling headers & build steps
• tsup.config.*.ts & tsconfig.json for compilation
• package.json, ESLint/Prettier configs
README for additional context
• CSense is an open-source CCW security auditing tool.
• No server-side component; the tool runs entirely in the browser.
• It relies on external CCW APIs (chain data + VM execution services).
Main components
A. Browser-hosted front-end (container)
– UI Layer
• Scene Manager (from src/base/scene.js)
• Scenes (src/scene/*.js)
• Overlays (src/overlay/*.js)
– Editor & Sandbox
• Monaco Editor integration (src/base/monaco.js)
• Sandbox Runner (src/sandbox/index.js, sandbox.ts, bridge.ts)
– State & Utilities
• Global State (src/base/state.js)
• Utilities (src/util/*.js)
– Asset Loader
• Certs, static files (src/asset/cert.pem)
B. External Services (over HTTPS)
– CCW Data API (src/api/ccwdata.js)
– CCW VM Execution API (src/api/vmapi.js)
C. Build Pipeline (developer tooling, outside browser)
– TSUP bundler (tsup.config.*.ts)
– Build scripts (script/build.mjs, script/header.mjs)
– NPM scripts in package.json
Relationships and data flows
1. User opens the SPA → Browser loads bundled JS (via index.js).
2. Scene Manager renders the Home scene.
3. User writes or loads a CCW script in Monaco Editor.
4. Upon “analyze” action:
• Sandbox bridge sends script to sandbox runner → isolates execution.
• Sandbox runner invokes VM API (vmapi.js) to execute/inspect.
• Potentially fetches data from Chain Data API (ccwdata.js).
5. Results returned → Overlay/Result component displays vulnerabilities.
6. Utilities (cookie, encryption) manage user identity or persisted settings.
Architectural patterns & principles
• Modular front-end with clear separation:
• Presentation (Scenes/Overlays)
• Business Logic (Sandbox + API modules)
• Infrastructure/Utilities
• Sandbox isolation for untrusted code execution.
• Single-page, event-driven scene manager.
• Build-time bundling for shipping a single JS artifact.