{"_id":"@0xlayout/sentinel-security","name":"@0xlayout/sentinel-security","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@0xlayout/sentinel-security","version":"1.0.0","description":"Sentinel — Advanced secret scanner (v1) — Code never leaks.","keywords":["security","secret-scanner","ci","secrets","token","api-key"],"homepage":"https://sentinel-security-ss.vercel.app/","bugs":{"url":"https://github.com/0xlayout/sentinel/issues"},"repository":{"type":"git","url":"git+https://github.com/0xlayout/sentinel.git"},"license":"MIT","author":{"name":"0xlayout"},"type":"commonjs","main":"bin/sentinel.js","bin":{"sentinel":"bin/sentinel.js"},"directories":{"doc":"docs"},"scripts":{"start":"node bin/sentinel.js","scan":"node bin/sentinel.js","test":"jest --verbose"},"dependencies":{"cli-progress":"^3.12.0","cli-table3":"^0.6.5","colorette":"^2.0.20","crypto":"^1.0.1","he":"^1.2.0","jsdom":"^22.1.0","ora":"^9.0.0","yaml":"^2.2.1"},"devDependencies":{},"engines":{"node":">=18"},"gitHead":"b88fb7d691f3355f5c7278ede393c3087b9a8122","_id":"@0xlayout/sentinel-security@1.0.0","_nodeVersion":"22.20.0","_npmVersion":"11.6.4","dist":{"integrity":"sha512-u9QoXwHSkoyArpNKpdJYXi5k5BVft8PYuXn+u1H+uZntQKqPNIlSAQGswwM8PcH6EwIGZ7V5LbCBWS3MAIT24Q==","shasum":"6c00d9f32d7ab121768f9db6cbdff5996493bde7","tarball":"https://registry.npmjs.org/@0xlayout/sentinel-security/-/sentinel-security-1.0.0.tgz","fileCount":27,"unpackedSize":69529,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDBOlYnpY4DrSW62XyFTpIGq9GP18rTzzmA9RsDCuNvBgIhANwBeync8T7eJFRXschLZ0dUFwC4jgaVmUHiO5+M6Wup"}]},"_npmUser":{"name":"0xlayout","email":"0xlayout@atomicmail.io"},"maintainers":[{"name":"0xlayout","email":"0xlayout@atomicmail.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sentinel-security_1.0.0_1765905734529_0.6975629223379962"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-16T17:22:14.380Z","1.0.0":"2025-12-16T17:22:14.712Z","modified":"2025-12-16T17:22:15.025Z"},"maintainers":[{"name":"0xlayout","email":"0xlayout@atomicmail.io"}],"description":"Sentinel — Advanced secret scanner (v1) — Code never leaks.","homepage":"https://sentinel-security-ss.vercel.app/","keywords":["security","secret-scanner","ci","secrets","token","api-key"],"repository":{"type":"git","url":"git+https://github.com/0xlayout/sentinel.git"},"author":{"name":"0xlayout"},"bugs":{"url":"https://github.com/0xlayout/sentinel/issues"},"license":"MIT","readme":"

\r\n\r\n

\r\n███████╗ ███████╗ ███╗   ██╗ ████████╗ ██╗ ███╗   ██╗ ███████╗ ██╗     \r\n██╔════╝ ██╔════╝ ████╗  ██║ ╚══██╔══╝ ██║ ████╗  ██║ ██╔════╝ ██║     \r\n███████╗ █████╗   ██╔██╗ ██║    ██║    ██║ ██╔██╗ ██║ █████╗   ██║     \r\n╚════██║ ██╔══╝   ██║╚██╗██║    ██║    ██║ ██║╚██╗██║ ██╔══╝   ██║     \r\n███████║ ███████╗ ██║ ╚████║    ██║    ██║ ██║ ╚████║ ███████╗ ███████╗\r\n╚══════╝ ╚══════╝ ╚═╝  ╚═══╝    ██║    ╚═╝ ╚═╝  ╚═══╝ ╚══════╝ ╚══════╝\r\n
\r\n

\r\n

\r\n\r\n \"NPM\r\n \"GitHub\r\n \r\n \"Email\"\r\n\r\n \r\n \"Made\r\n\r\n

\r\n\r\n\r\n\r\nPrevent Code Leaks in Your Projects\r\n\r\nSentinel is an advanced secret scanning tool designed for developers, security engineers, and CI/CD pipelines. It helps prevent sensitive information, credentials, and API keys from leaking into public repositories or production environments by scanning codebases before deployment.\r\n\r\nThis documentation covers installation, usage, configuration, advanced features, reporting, examples, integration into pipelines, best practices, troubleshooting, and contributing guidelines.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n1. [Features](#features)\r\n2. [Installation](#installation)\r\n3. [Usage](#usage)\r\n4. [Options](#options)\r\n5. [Architecture](#architecture)\r\n6. [Scanners](#scanners-details)\r\n7. [Advanced Examples](#advanced-examples)\r\n8. [Configuration & Customization](#configuration--customization)\r\n9. [Reporting](#reporting)\r\n10. [CI/CD Integration](#cicd-integration)\r\n11. [Best Practices](#best-practices)\r\n12. [Troubleshooting & FAQ](#troubleshooting--faq)\r\n13. [Contributing](#contributing)\r\n14. [License](#license)\r\n\r\n---\r\n\r\n## Features\r\n\r\n| Feature | Description |\r\n| -------------------------- | ------------------------------------------------------------------------------------------------------------ |\r\n| **Regex Scanner** | Detects secrets using predefined and custom provider rules for AWS, GitHub, Stripe, Google, Slack, and more. |\r\n| **Entropy Scanner** | Identifies high-entropy strings likely to be passwords, tokens, or cryptographic keys. |\r\n| **Heuristic Scanner** | Detects suspicious keywords and patterns in source and configuration files. |\r\n| **Multi-format Reporting** | Outputs scan results to Terminal, JSON, and HTML. |\r\n| **Fast & Deep Scans** | Choose between quick regex-only scans or full deep scans including entropy and heuristics. |\r\n| **Extensible** | Add custom provider rules via JSON files without changing the code. |\r\n| **CI/CD Friendly** | Seamless integration with GitHub Actions, GitLab CI, Jenkins, and other CI/CD platforms. |\r\n| **Deduplication** | Removes duplicate findings to ensure clean reports. |\r\n\r\n---\r\n\r\n## Installation\r\n\r\nInstall the package from npm:\r\n\r\n```bash\r\nnpm install -g @0xlayout/sentinel-security\r\n```\r\n\r\n> [!NOTE]\r\n> The -g flag makes the sentinel CLI available globally.\r\n\r\nLocally:\r\n\r\nClone the repository and install dependencies:\r\n\r\n```bash\r\ngit clone https://github.com/0xlayout/sentinel.git\r\ncd sentinel\r\nnpm install\r\nnpm link\r\n```\r\n\r\nRun the CLI:\r\n\r\n```bash\r\nnpm link\r\nsentinel \r\n```\r\n\r\nOr:\r\n\r\n```bash\r\nnode bin/sentinel.js \r\n```\r\n\r\n**Important:**\r\nBefore scanning, remove or ignore folders that do not contain source code or sensitive information to improve scan speed and reduce false positives:\r\n\r\n* `.git`\r\n* `assets`\r\n* `node_modules` (unless scanning dependencies is desired)\r\n* `dist` / `build` / other auto-generated folders\r\n\r\n---\r\n\r\n## Usage\r\n\r\n### Basic Scan (Fast)\r\n\r\n```bash\r\nsentinel /path/to/project --fast\r\n```\r\n\r\n* Performs a fast scan using only regex rules.\r\n* Outputs results to Terminal.\r\n\r\n### Deep Scan (Full)\r\n\r\n```bash\r\nsentinel /path/to/project --deep --json --html\r\n```\r\n\r\n* Runs Regex, Entropy, and Heuristic scans.\r\n* Generates structured `JSON` and human-readable `HTML` reports.\r\n* Suitable for CI/CD and security audits.\r\n\r\n### Ignore Specific Directories\r\n\r\n```bash\r\nsentinel /path/to/project --deep --ignore node_modules dist test\r\n```\r\n\r\n* Excludes specific directories from scanning.\r\n* Useful for large projects or third-party dependencies.\r\n\r\n---\r\n\r\n## Options\r\n\r\n| Option | Description |\r\n| -------------------- | ----------------------------------------------------------- |\r\n| `--help, -h` | Displays the version of Sentinel |\r\n| `--version, -V` | Displays the help panel |\r\n| `` | Directory to scan (required) |\r\n| `--fast` | Fast scan using only regex rules |\r\n| `--deep` | Full scan including regex, entropy, and heuristic detection |\r\n| `--json` | Generate JSON report (`sentinel_report.json`) |\r\n| `--html` | Generate HTML report (`sentinel_report.html`) |\r\n| `--ignore ` | List of directories to ignore during scan |\r\n\r\n---\r\n\r\n## Architecture\r\n\r\nSentinel is modular and consists of the following components:\r\n\r\n1. **File Loader**\r\n\r\n * Recursively loads files from the target directory.\r\n * Filters out ignored paths.\r\n * Supports large codebases efficiently.\r\n\r\n2. **Scanners**\r\n\r\n * **RegexScanner:** Matches secrets with predefined and custom rules.\r\n * **EntropyScanner:** Detects high-entropy strings.\r\n * **HeuristicScanner:** Detects suspicious keywords and insecure patterns.\r\n\r\n3. **Deduplication**\r\n\r\n * Ensures each secret is reported only once.\r\n * Uses a combination of file path, line number, and matched content.\r\n\r\n4. **Reporting**\r\n\r\n * Terminal output for quick review.\r\n * JSON for CI/CD consumption.\r\n * HTML for visual, human-readable reports.\r\n\r\n---\r\n\r\n## Scanners Details\r\n\r\n### Regex Scanner\r\n\r\n* Detects patterns of known secrets like API keys, tokens, and credentials.\r\n* Supports custom JSON-based rules.\r\n* High performance, suitable for large codebases.\r\n\r\n### Entropy Scanner\r\n\r\n* Measures Shannon entropy of strings.\r\n* Flags strings with unusually high entropy as potential secrets.\r\n* Ideal for passwords, encryption keys, and API secrets.\r\n\r\n### Heuristic Scanner\r\n\r\n* Scans for keywords such as `password`, `secret`, `token`, `apikey`.\r\n* Detects suspicious patterns and commented-out secrets.\r\n\r\n---\r\n\r\n## Advanced Examples\r\n\r\n| Example | Command / YAML / JSON | Description |\r\n| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\r\n| **Fast Scan** | `sentinel ./my-project --fast` | Quick scan using regex only. Results printed in Terminal. |\r\n| **Deep Scan** | `sentinel ./my-project --deep --json --html` | Full scan using Regex, Entropy, Heuristic. Generates JSON and HTML reports. |\r\n| **Ignore Directories** | `sentinel ./my-project --deep --ignore node_modules dist test` | Excludes specific directories from scanning. |\r\n| **CI/CD GitHub Actions** | `yaml name: Sentinel Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Node.js uses: actions/setup-node@v3 with: node-version: '18' - run: npm ci - run: sentinel . --deep --json - name: Upload Sentinel Report uses: actions/upload-artifact@v3 with: name: sentinel-report path: sentinel_report.json ` | Automatic scan on push/pull request. Uploads JSON report as artifact. |\r\n| **Custom Provider Rules** | `json { \"rules\": [ { \"name\": \"custom_api_key\", \"pattern\": \"custom_[0-9a-zA-Z]{20}\" } ] } ` | Place JSON in `src/scanners/providerRules/`. Run Sentinel with `--deep`. Custom rules included automatically. |\r\n\r\n---\r\n\r\n## Configuration & Customization\r\n\r\n1. **Adding Custom Rules**\r\n\r\n * Create a `.json` file in `src/scanners/providerRules/`.\r\n * Each rule must have a `name` and `pattern` (regex).\r\n\r\n2. **Excluding Files/Folders**\r\n\r\n * Use `--ignore` option to skip irrelevant directories.\r\n * Recommended: `.git`, `assets`, `node_modules`, `dist`.\r\n\r\n3. **Adjusting Scan Depth**\r\n\r\n * `--fast`: Only regex, minimal processing.\r\n * `--deep`: Full scan, including entropy and heuristics.\r\n\r\n---\r\n\r\n## Reporting\r\n\r\n* **Terminal:** Quick overview for development.\r\n* **JSON:** Structured, ideal for pipelines. Includes file, line, type, and matched value.\r\n* **HTML:** Human-readable report with color-coded severity and summary statistics.\r\n\r\n**Example JSON Entry:**\r\n\r\n```json\r\n{\r\n \"file\": \"src/config.js\",\r\n \"line\": 12,\r\n \"type\": \"AWS_SECRET_KEY\",\r\n \"match\": \"AKIA************\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## CI/CD Integration\r\n\r\n* **GitHub Actions:** Automatically scan on push or pull request. Upload artifacts.\r\n* **GitLab CI:** Use `script` section to run Sentinel and store reports as artifacts.\r\n* **Jenkins:** Include `node` build step with `npm install` and run `sentinel.js`.\r\n\r\n**Best Practice:** Integrate into pre-deploy or pre-merge pipelines to prevent secrets from entering production.\r\n\r\n---\r\n\r\n## Best Practices\r\n\r\n* Exclude `.git`, `node_modules`, and generated folders to reduce false positives.\r\n* Regularly update provider rules.\r\n* Run deep scans before production deployment.\r\n* Use custom rules for internal APIs or unique token patterns.\r\n* Combine JSON reports with automated alerting in pipelines.\r\n\r\n---\r\n\r\n## Troubleshooting & FAQ\r\n\r\n**Q:** Some files are not scanned.\r\n**A:** Ensure they are not ignored via `--ignore` and check file permissions.\r\n\r\n**Q:** False positives detected.\r\n**A:** Review the rules in `src/scanners/providerRules/` and refine regex patterns.\r\n\r\n**Q:** Scan takes too long.\r\n**A:** Use `--fast` or exclude large directories like `node_modules`.\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nSentinel is open-source. Contributions welcome:\r\n\r\n* Add or improve provider rules (`src/scanners/providerRules/*.json`).\r\n* Enhance scanner performance or add new strategies.\r\n* Fix bugs, improve tests, or enhance documentation.\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the **[MIT License](./LICENSE)**.\r\n\r\nYou are free to use, modify, distribute, and integrate this software in both \r\nopen-source and commercial projects — as long as you include the copyright notice below.\r\n\r\n\r\n\r\n---\r\n\r\n\r\n\r\n
\r\n
\r\n \"made-with-love\"\r\n
\r\n

\r\n By 0xlayout\r\n

\r\n\r\n
\r\n","readmeFilename":"README.md","_rev":"1-e1dcb7edbe5d6a56ba226ce572bb5109"}