@bytehide/secrets-scanner
Version:
AI-powered secrets scanner for JavaScript/TypeScript. Detects and protects API keys, tokens, and credentials in source code and build artifacts. Features automatic fixing, built-in secrets manager, and zero-knowledge privacy. Superior alternative to gitle
330 lines (236 loc) • 19.2 kB
Markdown
# ByteHide Secrets Scanner for JavaScript/TypeScript ⚡
**ByteHide Secrets Scanner** is a lightweight, powerful secret detection tool for JavaScript/TypeScript projects. It integrates directly into your build process to scan and protect your code from accidentally exposing sensitive data such as API keys, tokens, and passwords. It goes beyond traditional scanners by also analyzing your **post-compilation artifacts** and offering advanced AI-based detection (in its advanced version) with a secure, zero-knowledge approach.
[](https://www.npmjs.com/package/@bytehide/secrets-scanner)
[](https://www.npmjs.com/package/@bytehide/secrets-scanner)
[](https://github.com/ByteHide/bytehide-secrets-scanner-js/blob/main/LICENSE)
📚 [**Official Documentation**](https://docs.bytehide.com/platforms/javascript/products/secrets)
---
## Important Security Notice
**Stay Cool & Secure:**
- **Local & Private:** All scanning is performed on your machine. Neither your source code nor your artifacts ever leave your environment—total privacy guaranteed!
- **Beyond Source Code:** Unlike other scanners, ByteHide Secrets Scanner goes the extra mile by scanning your **post-compilation artifacts**. This means it can catch secrets that might be injected during the build process and hidden from plain sight in your source code.
- **Built-In Secrets Manager:** No need for a separate service. Export and manage your secrets in the ByteHide platform at no extra cost.
Enjoy the peace of mind knowing that your secrets are covered from every angle.
---
## Compatibility
- **JavaScript & TypeScript**: Full support for modern JS/TS syntax including ES6+, JSX, TSX
- **Node.js**: Compatible with Node.js 16+ and all major package managers (npm, yarn, pnpm)
- **Frameworks**: Works with React, Vue, Angular, Next.js, Nuxt.js, Express, and more
- **Build Tools**: Integrates seamlessly with Webpack, Vite, Rollup, Parcel, and custom build processes
- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI, and more
- **File Types**: Scans `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.env`, and configuration files
---
## Installation
```bash
npm install @bytehide/secrets-scanner
```
Or if you prefer Yarn:
```bash
yarn add @bytehide/secrets-scanner
```
This will install the scanner in your project, providing the CLI command `bytehide-secrets`.
---
## Getting Started
### 1. Obtain a Free Token
1. Create a free account at [cloud.bytehide.com/register](https://cloud.bytehide.com/register).
2. Set up a **Secrets** project and grab your **Project Token**.
3. Keep this token **private**—do not commit it to Git.
### 2. Initialize Your Project
Use the **init** command to create a `bytehide.secrets.json` config file and optionally add a prebuild script to your `package.json`:
```bash
npx bytehide-secrets init
```
During `init`, you’ll be prompted to:
- Enter your ByteHide token (to sync secrets and analysis results).
- Configure scanning behaviors (e.g., whether to generate a local report, anonymize secrets, or enable `fix` mode).
- Optionally add `"prebuild": "bytehide-secrets scan"` to your `package.json` to scan your repository before any build.
**Tip**: You can store the token in your `.env` file instead of the JSON to avoid committing it.
### 3. Run a Scan
After initialization, manually scan your project:
```bash
npx bytehide-secrets scan
```
Or rely on the prebuild script if you added one:
```bash
npm run build
```
The scanner will:
1. Load your config from `bytehide.secrets.json` (unless overridden by CLI args).
2. Load environment variables (e.g., `BYTEHIDE_SECRETS_TOKEN`).
3. Detect secrets in source code **and** post-compilation artifacts.
4. Export findings to the ByteHide manager if configured.
---
## If You’re Not Using the `init` Command
You can still configure the scanner manually by creating a file named **`bytehide.secrets.json`** at the root of your project. Here’s an example structure:
```json
{
"token": "<your-token-here>",
"appName": "my-v0-project",
"environment": "production",
"sync": true,
"report": "",
"reportFormat": "json",
"anonymize": false,
"fix": true
}
```
- **`token`**: Your ByteHide project token.
- **`appName`**: The name shown in the ByteHide dashboard for this project.
- **`environment`**: The environment used when exporting secrets (e.g., `"production"`, `"staging"`).
- **`sync`**: If `true`, exports secrets to the ByteHide Secrets manager.
- **`report`**: If non-empty, the path where a local report (JSON or YAML) will be written.
- **`reportFormat`**: Either `"json"` or `"yaml"`.
- **`anonymize`**: If `true`, scrubs the actual secret values in logs and reports.
- **`fix`**: If `true`, automatically removes or replaces hardcoded secrets.
> **Note**: For security reasons, consider **not** storing your token directly in `bytehide.secrets.json`. Instead, store it in an environment variable (e.g., `BYTEHIDE_SECRETS_TOKEN`) or a private `.env` file:
> ```bash
> BYTEHIDE_SECRETS_TOKEN=<your-token>
> BYTEHIDE_SECRETS_ENVIRONMENT=production
> ```
> The scanner automatically merges these environment variables with your JSON and CLI arguments, so you can omit `token` or `environment` from the JSON if you prefer.
## Usage
### CLI Commands
#### `init`
Prompts you for config details and optionally creates/updates `bytehide.secrets.json` + a `prebuild` script:
```bash
npx bytehide-secrets init
```
**What It Does**:
- Asks for your ByteHide token (or environment usage).
- Lets you specify environment, sync, local reporting, anonymizing secrets, etc.
- Optionally adds `"prebuild": "bytehide-secrets scan"` to your `package.json`.
#### `scan`
Performs secret detection and optionally fixes or exports:
```bash
npx bytehide-secrets scan [options]
```
>If you’ve already run **`init`** (or created a `bytehide.secrets.json` manually), you can simply run:
>```bash
>npx bytehide-secrets scan
>```
>with **no arguments**, and the scanner will read all configuration (token, environment, fix mode, etc.) from your JSON (and/or environment variables). This is the same approach used when adding `"prebuild": "bytehide-secrets scan"` in your `package.json`.
**Key Options**:
- `--path <folder>`
Path to the folder you want to scan (defaults to `.`).
- `--token <string>`
ByteHide project token. Overrides any token found in the JSON or environment variables (default `""`).
- `--appName <string>`
Application name used in the analysis (default `"MyApp"`).
- `--environment <string>`
Manager environment (default `"production"`).
- `--sync <bool>`
If `true`, exports secrets to the ByteHide manager (default `true`).
- `--report <string>`
Path to export the final analysis (JSON or YAML). Defaults to `""` (no report).
- `--reportFormat <string>`
Format of the exported report: `"json"` or `"yaml"` (default `"json"`).
- `--anonymize <bool>`
If `true`, scrubs secret values in logs/reports (default `false`).
- `--fix <bool>`
Automatically remove or replace hardcoded secrets with calls to `@bytehide/secrets` (default `false`).
### Automatic Fixing
If you pass `--fix true`, the scanner attempts to **remove** or **replace** hardcoded secrets. It injects:
```js
import { SecretsManager } from "@bytehide/secrets";
```
...and transforms recognized strings into:
```js
await Secrets.get("autoGeneratedKey");
```
(or a synchronous call if not in an async function). Check your Git diff before committing these changes.
---
## Sample Workflow
1. **Initialize** your project:
```bash
npx bytehide-secrets init
```
2. **Set** your token in `.env` or `bytehide.secrets.json`.
3. **Add** a prebuild script in your `packages.json` to automatically scan:
```json
{
"scripts": {
"prebuild": "bytehide-secrets scan",
"build": "webpack"
}
}
```
4. **Build** your project:
```bash
npm run build
```
or
```bash
yarn build
```
The scanner runs first, preventing accidental leaks.
---
## Benefits and Use Cases
- **Enhanced Security**: Avoid shipping tokens in source code or compiled bundles.
- **Auto-Fix**: Remove or replace secrets automatically—no manual hunt.
- **Integrated Secrets Manager**: Manage your secrets in ByteHide’s free manager.
- **Advanced Detection**: Post-compilation scanning + AI-based detection catch secrets other tools miss.
- **Local & Private**: All scanning is done on your machine, code never leaves your environment.
---
## Why Choose ByteHide Secrets Scanner?
1. **All-in-One**: Detect secrets, fix them, and manage them—no extra tools required.
2. **Post-Compilation Artifacts**: Catches secrets injected at build time.
3. **Built-In Manager**: Export to ByteHide’s secure manager at no cost.
4. **Zero-Knowledge AI**: Respects your code’s privacy.
5. **Minimal Overhead**: Simple to integrate into your workflow or CI/CD.
---
## Getting a Free Token
1. Sign up at [cloud.bytehide.com/register](https://cloud.bytehide.com/register).
2. Create a **Secrets** project for JavaScript/TypeScript.
3. Copy the **Project Token**.
4. Add it to `.env` as `BYTEHIDE_SECRETS_TOKEN` or store it in `bytehide.secrets.json`.
> **SECURITY WARNING**
> Never commit your `bytehide.secrets.json` or `.env` to a public repo. These files contain sensitive data.
---
## Get Started Today!
**Secure your JavaScript/TypeScript code now!**
- **Install**: `npm install @bytehide/secrets-scanner`
- **Initialize**: `npx bytehide-secrets init`
- **Scan**: `npx bytehide-secrets scan` or run automatically on build
Visit our [official documentation](https://docs.bytehide.com/platforms/javascript/products/secrets) for more details, or join our community for support and advanced usage tips.
## Detection Features
ByteHide Secrets Scanner combines **multiple detection methods** to catch a wide range of secrets, tokens, and credentials in your code and build artifacts. Below is an overview of its **plugin-based architecture** and how each feature works:
| **Feature / Detector** | **Description** |
|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Regex-Based Detection** | Utilizes thousands of pattern-based rules (over 6,000 lines) to match known secret formats (API keys, tokens, credentials, etc.). This ruleset is continuously updated to cover popular providers, frameworks, and typical naming conventions. |
| **Entropy-Based Detection** | Calculates the Shannon entropy of strings to identify high-entropy values (random-looking sequences). This helps detect secrets that don’t match typical patterns (e.g., base64-encoded keys, JWTs, or custom credentials). |
| **Keyword/Context Detection** | Flags strings based on sensitive keywords or variable names (e.g., `password`, `secretKey`, `token`) combined with contextual analysis. This approach reduces false positives by ensuring the string is indeed used in a sensitive context. |
| **Plugin Extensions (by Provider)** | The scanner ships with multiple **provider-specific** detectors: |
| **AWS** | Detects AWS access and secret keys, IAM tokens, or other AWS-specific credentials. |
| **Azure** | Scans for Azure Storage keys, SAS tokens, or other Azure credentials. |
| **GitHub** | Detects GitHub personal access tokens and GitHub OAuth secrets. |
| **GitLab** | Catches GitLab personal tokens, OAuth secrets, etc. |
| **Discord** | Finds Discord bot tokens and application secrets. |
| **Mailchimp** | Flags Mailchimp API keys. |
| **IBM Cloud** | Checks for IBM Cloud IAM keys, COS HMAC credentials, etc. |
| **Slack** | Identifies Slack bot tokens, Slack signing secrets, etc. |
| **Square OAuth** | Looks for Square OAuth secrets or client tokens. |
| **Npm** | Detects NPM tokens or keys used for package publishing. |
| **Stripe** | Flags Stripe secret keys (sk_live, sk_test, etc.). |
| **Twilio** | Detects Twilio account tokens and API keys. |
| **PrivateKey** | Catches private keys (RSA, PEM files, etc.) that may be inadvertently checked in. |
| ... and more ... | Additional plugins for other providers (e.g., Cloudant, SendGrid, SoftLayer) are included, with more to come. |
| **AI-Based Detection (Paid)** | An optional advanced feature using zero-knowledge AI to identify non-traditional secrets or project-specific patterns that don’t match standard rules or providers. This requires a premium ByteHide plan to activate. |
| **Post-Compilation Analysis** | Goes beyond source code by scanning compiled artifacts (e.g., `.js`, `.ts`, `.tsx`, or even minified builds) to detect secrets injected at build time. |
| **Comprehensive Rules** | Over 6,000 lines of detection logic covering providers, frameworks, naming conventions, and custom patterns, ensuring minimal false negatives. |
| **Free Integrated Manager** | Automatically export detected secrets to ByteHide’s built-in secrets manager (if `sync` is enabled). This is optional but offers an all-in-one workflow for secret storage and rotation. |
> **Note**: You can configure or disable certain detectors if you have project-specific needs. For more details, check the ByteHide documentation or customize your `bytehide.secrets.json` accordingly.
With this **multi-pronged detection strategy**—regex rules, entropy analysis, context-based scanning, provider-specific plugins, and optional AI—ByteHide Secrets Scanner significantly reduces the chance of missing any secret while keeping false positives to a minimum.
### Multi-Language Support
Although this package focuses on **JavaScript/TypeScript**, ByteHide Secrets Scanner also supports:
- **.NET** via [ByteHide Secrets Scanner for .NET](https://github.com/bytehide/bytehide-secrets-scanner-dotnet)
- Direct **Git repository** scanning (detecting secrets in any language)
- **Auto-fix** integrations for various languages and build systems
Check our other repositories and packages to see how ByteHide Secrets can protect your entire stack.
---
### Security & Feedback
We’re committed to keeping your code secure. If you find any issues or have feedback on ByteHide Secrets Scanner, please reach out:
- **Email**: security@bytehide.com
- **GitHub Issues**: [Open an issue](https://github.com/bytehide/bytehide-secrets-scanner/issues)
- **Community Forum**: Coming soon!
We appreciate your help in making ByteHide Secrets the best tool for preventing secret leaks.