Sinker is a minimalistic security tool designed to scan your codebase for potentially dangerous "sinks" (e.g., document.URL, innerHTML, localStorage) that could lead to vulnerabilities like DOM XSS or data leakage.

Designed for modern web development, Sinker integrates seamlessly into CI/CD pipelines to alert developers of unprotected sinks before they reach production.

• Features
• Quick Start
  • Installation
  • Usage
  • ESLint Plugin
  • CLI Options
• Configuration
• Suppressing Findings
• Contributing
• Changelog
• Security
• Inspiration
• License

• Recursive Scanning: Automatically scans .ts, .js, .html, and other relevant files.
• ESLint Plugin: Use it as a real-time linter for better IDE integration.
• Highly Customizable: Load project-specific sinks and sources via a configuration file.
• Safe Bypassing: Explicitly flag intentional usage of sinks as safe with inline comments.
• CI Ready: Returns non-zero exit codes on violations, making it perfect for automated security gates.
• Contextual Reports: See the exact line and surrounding code for every finding.

# Using npm
npm install @webklex/sinker --save-dev

Please take a look at the ESLint Plugin README for detailed information.

Run a scan on your project:

npx sinker .

Add the plugin to your eslint.config.js (Flat Config):

const sinkerPlugin = require('@webklex/sinker/eslint-plugin');

module.exports = [
    {
        files: ['**/*.js', '**/*.ts'],
        plugins: {
            sinker: sinkerPlugin,
        },
        rules: {
            'sinker/no-sink': ['warn', { contextDepth: 10 }],
        },
    },
];

Or use the recommended configuration:

const sinkerPlugin = require('@webklex/sinker/eslint-plugin');

module.exports = [sinkerPlugin.configs.recommended];

Example:

npx sinker src --context-depth=5 --no-color

Sinker looks for a sinker.config.js file in your project root.

module.exports = {
    // Define custom sinks to watch for
    sinks: [
        {
            name: 'CUSTOM_STORAGE',
            description: 'Potential sensitive data leakage to custom storage',
            link: 'https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage',
            displayContextBefore: true,
            displayContextAfter: true,
            sinks: ['myApp.storage.set'],
        },
    ],
    // Ignore specific built-in sinks
    ignoredSinks: ['document.URL'],
    // Paths to exclude from scanning
    ignored: [
        '**/node_modules/**',
        '**/dist/**',
        '**/coverage/**',
        '**/*.test.ts',
        '**/*.spec.ts',
    ],
    colors: true,
    minimal: false,
    contextDepth: 3,
};

• sinks (Array): Custom sink definitions.
• ignoredSinks (String[]): List of sink names/patterns to ignore globally.
• ignored (String[]): Glob patterns for files or directories to skip.
• colors (Boolean): Toggle colored output.
• minimal (Boolean): Minimal output format.
• contextDepth (Number): Number of lines of context to display around violations.

If a sink usage is intentional and properly protected (e.g., sanitized with DOMPurify), you can suppress the alert by adding a @safe-sink comment on the line immediately preceding the sink.

// @safe-sink: Content is sanitized via DOMPurify
element.innerHTML = sanitizedContent;

<!-- @safe-sink: URL is validated against an allowlist -->
<script>
    const url = document.URL;
</script>

To contribute to the built-in sink definitions:

1. Create a new definition file in src/sinks/ (e.g., src/sinks/framework_sinks.ts):

   import { Sink } from './types';
   export const frameworkSinks: Sink = {
       name: 'Framework Sinks',
       description: 'Dangerous sinks specific to X framework.',
       link: 'https://example.com/security-docs',
       displayContextBefore: true,
       displayContextAfter: true,
       sinks: ['X.unsafeMethod'],
   };

2. Register it in src/sinks/index.ts:

   import { frameworkSinks } from './framework_sinks';
   export const allSinkGroups: Sink[] = [
       // ... existing groups
       frameworkSinks,
   ];

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Generate coverage report
npm run test:coverage

Please see CHANGELOG for more information what has changed recently.

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

• Sources and Sinks Cheatsheet
• eslint-plugin-no-unsanitized

The MIT License (MIT). Please see License File for more information.