{"id":25306557,"url":"https://github.com/pixincreate/keywatch","last_synced_at":"2025-04-07T06:29:00.846Z","repository":{"id":277219074,"uuid":"931722116","full_name":"pixincreate/KeyWatch","owner":"pixincreate","description":"KeyWatch – the vigilant guardian that sniffs out hidden keys and secrets in your code with a wink and a nod.","archived":false,"fork":false,"pushed_at":"2025-04-01T17:15:04.000Z","size":80,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T18:27:05.721Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pixincreate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-12T18:43:45.000Z","updated_at":"2025-04-01T17:15:06.000Z","dependencies_parsed_at":"2025-04-01T18:34:11.449Z","dependency_job_id":null,"html_url":"https://github.com/pixincreate/KeyWatch","commit_stats":null,"previous_names":["pixincreate/keywatch"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixincreate%2FKeyWatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixincreate%2FKeyWatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixincreate%2FKeyWatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixincreate%2FKeyWatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pixincreate","download_url":"https://codeload.github.com/pixincreate/KeyWatch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247604604,"owners_count":20965456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-13T10:35:38.377Z","updated_at":"2025-04-07T06:29:00.829Z","avatar_url":"https://github.com/pixincreate.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KeyWatch\n\nKeyWatch is a secret scanner written in Rust that analyzes files or directories for secrets such as API keys, passwords, tokens, and more. It leverages a flexible and configurable set of detectors (defined via a TOML configuration) to help you secure your codebase by catching accidental exposures early. Whether you’re integrating it into your CI/CD pipeline or using it as a pre-commit hook, KeyWatch is designed to be fast, efficient, and easily extendable.\n\n## Table of Contents\n\n- [Features](#features)\n- [Project Structure](#project-structure)\n- [Installation](#installation)\n  - [Prerequisites](#prerequisites)\n  - [Building from Source](#building-from-source)\n  - [Installing the Binary](#installing-the-binary)\n- [Usage](#usage)\n  - [Scanning Files and Directories](#scanning-files-and-directories)\n  - [Windows Users](#windows-users)\n- [Adding More Detectors](#adding-more-detectors)\n- [Integration with pre-commit](#integrating-keywatch-with-pre-commit)\n- [Running Tests](#running-tests)\n- [License](#license)\n\n## Features\n\n- **Recursive Scanning:** Easily scan a single file or an entire directory recursively to detect potential security breaches.\n- **Comprehensive Detection:** The built-in detectors cover AWS keys, Google API keys, Slack tokens, JWT tokens, SSH keys, passwords, email addresses, IP addresses, and many more.\n- **Configurable Detectors:** The detection logic is defined in [`detectors.toml`], which is simple to extend or customize according to your needs.\n- **Output Options:** Generate JSON-formatted reports that can be directed to the console (in verbose mode) or saved to a file.\n- **Integration Ready:** Designed to integrate with CI/CD pipelines, pre-commit hooks, or any other automated workflow.\n\n## Project Structure\n\nThe KeyWatch project is organized as follows:\n\n```txt\nKeyWatch/\n├── .gitignore               # Specifies intentionally untracked files to ignore.\n├── Cargo.lock               # Cargo's lock file ensuring reproducible builds.\n├── Cargo.toml               # Project manifest (dependencies, metadata, etc.)\n├── LICENSE                  # MIT License file.\n├── README.md                # This documentation file.\n├── detectors.toml           # Configuration file defining secret detectors and regex patterns.\n├── src\n│   ├── cli.rs             // Contains CLI definitions using clap.\n│   ├── detector.rs        // Implements secret detectors and regex patterns.\n│   ├── lib.rs             // Re-exports modules for integration testing.\n│   ├── main.rs            // Application entry point.\n│   ├── report.rs          // Generates JSON reports from scan results.\n│   ├── scanner.rs         // Implements file and directory scanning.\n│   └── utils.rs           // Contains utility functions (e.g., file I/O).\n└── tests\n    └── integration_tests.rs  // Integration tests for end-to-end functionality.\n```\n\nThe relationships between key modules are illustrated below:\n\n```mermaid\ngraph TD\n    A[main.rs] --\u003e B[cli.rs]\n    A --\u003e C[scanner.rs]\n    C --\u003e D[detector.rs]\n    D --\u003e E[detectors.toml]\n    C --\u003e F[report.rs]\n    A --\u003e G[utils.rs]\n```\n\n## Installation\n\n### Prerequisites\n\n- [Rust](https://www.rust-lang.org/tools/install) (version 1.70 or later) must be installed on your system.\n- Linux and macOS users: Standard Unix tools (`grep`, `chmod`, etc.) should be available.\n- Windows users: Consider installing Git Bash or enabling Windows Subsystem for Linux (WSL2) for an enhanced Unix-like experience, though native Windows commands work as well.\n\n### Building from Source\n\n1. Clone the repository:\n\n   ```sh\n   git clone https://github.com/pixincreate/KeyWatch.git\n   cd KeyWatch\n   ```\n\n2. Build the project using Cargo:\n\n   ```sh\n   cargo build\n   ```\n\n   This command compiles the KeyWatch binary into the `target/debug` directory.\n\n### Installing the Binary\n\nYou can install KeyWatch globally so it is available from any command prompt:\n\n1. **Cargo Install (Recommended):**\n\n   Run the following command from the KeyWatch directory:\n\n   ```sh\n   cargo install --path .\n   ```\n\n\u003e [!NOTE]\n\u003e This command copies the binary to Cargo’s bin directory (typically `~/.cargo/bin` on Unix or `%USERPROFILE%\\.cargo\\bin` on Windows), which should be part of your `PATH` already.\n\u003e This will let you invoke the binary simply by typing `key-watch`.\n\n2. **Manual Installation:**\n\n   You may manually copy the binary into a directory included in your PATH:\n\n   - **For Unix-based systems (Linux/macOS):**\n\n     ```sh\n     cp target/debug/key-watch /usr/local/bin\n     ```\n\n     Or create a symbolic link:\n\n     ```sh\n     ln -s /path/to/target/release/key-watch /usr/local/bin/key-watch\n     ```\n\n   - **For Windows (PowerShell):**\n\n     1. Navigate to the release directory:\n\n        ```ps1\n        cd target\\release\n        ```\n\n     2. Copy the binary (e.g., `key-watch.exe`) to a directory that is part of your PATH (such as `C:\\Program Files\\KeyWatch`—ensure that directory is added to your PATH):\n\n        ```ps1\n        Copy-Item -Path \"key-watch.exe\" -Destination \"C:\\Program Files\\KeyWatch\\key-watch.exe\"\n        ```\n        \n        You can also add the `–Force` parameter if you want to overwrite the destination file without any prompts\n\n     3. Alternatively, you can add `%USERPROFILE%\\.cargo\\bin` to your system `PATH` if it’s not already included. This is where Cargo installs binaries by default.\n\n## Usage\n\n### Scanning Files and Directories\n\nAfter installing or building the binary, you can start scanning files for secrets:\n\n- **Scanning a Single File (Output to Console):**\n\n  ```sh\n  cargo run -- --file ./path/to/your/file --verbose\n  ```\n\n  This command scans the specified file and prints a detailed JSON report to the console.\n\n- **Recursively Scanning a Directory (Output to File):**\n\n  ```sh\n  cargo run -- --dir ./path/to/your/directory --output results.json\n  ```\n\n  The scanner will recursively inspect all eligible files within the directory tree, and the JSON report will be written to `results.json`.\n\n### Windows Users\n\nKeyWatch works well on Windows with a few adjustments:\n\n- **Using Command Prompt or PowerShell:**\n  The commands above work in either Command Prompt or PowerShell (preferred). Just ensure that Rust and Cargo are in your `PATH`, and that when installed via cargo, your binaries are located in `%USERPROFILE%\\.cargo\\bin`.\n\n- **Windows Environment Tips:**\n\n  - If using PowerShell, remember to escape arguments properly if needed.\n  - For better Unix-like behavior, consider installing Git Bash which provides a more consistent experience with the documentation examples.\n  - If integrating KeyWatch with Windows-based CI systems (e.g., Azure Pipelines), you may need to adjust the shell commands accordingly.\n\n- **Running on Windows:**\n\n  To run KeyWatch on a specific file from Command Prompt:\n\n  ```cmd\n  key-watch --file \"C:\\path\\to\\your\\file\" --verbose\n  ```\n\n  Or to scan a directory recursively:\n\n  ```cmd\n  key-watch --dir \"C:\\path\\to\\your\\directory\" --output \"C:\\path\\to\\results.json\"\n  ```\n\n## Adding More Detectors\n\nKeyWatch uses a flexible detector system configured via the [`detectors.toml`] file. You can modify this file to add new secret detectors or adjust the regular expressions and configurations of existing ones. For example:\n\n- Open `detectors.toml` in your preferred editor.\n- Define a new section with a unique identifier for your custom detector.\n- Provide the regex patterns, severity levels, and any additional metadata necessary.\n\nThis design means you can continuously tailor KeyWatch to meet the needs of your security policies.\n\n## Integrating KeyWatch with pre-commit\n\nIntegrate KeyWatch into your development workflow by setting it up as a pre-commit hook. This ensures that any secrets accidentally committed to your repository get caught immediately.\n\n1. **Install pre-commit:**\n\n   Ensure Python is installed on your system, then use pip:\n\n   ```sh\n   pip install pre-commit\n   ```\n\n\u003e [!NOTE]\n\u003e Make sure that you have the `pre-commit` binary in your PATH.\n\n2. **Create the Hook Script:**\n\n   1. Make a hooks directory in your project root:\n\n      ```sh\n      mkdir -p hooks\n      ```\n\n   2. Create a file named `hooks/keywatch.sh` with the following content:\n\n      ```sh\n      #!/bin/sh\n\n      EXIT_CODE=0\n      for FILE in \"$@\"; do\n        # Only scan text files\n        if file \"$FILE\" | grep -q text; then\n          echo \"Scanning $FILE for secrets...\"\n          REPORT=$(key-watch --file \"$FILE\" --verbose)\n          if echo \"$REPORT\" | grep -q '\"status\": \"FAIL\"'; then\n            echo \"Secret found in $FILE:\"\n            echo \"$REPORT\"\n            EXIT_CODE=1\n          fi\n        fi\n      done\n      exit $EXIT_CODE\n      ```\n\n   3. Make the script executable:\n\n      ```sh\n      chmod +x hooks/keywatch.sh\n      ```\n\n3. **Configure pre-commit:**\n\n   Create a `.pre-commit-config.yaml` file in your project root with these contents:\n\n   ```yaml\n   repos:\n     - repo: local\n       hooks:\n         - id: keywatch\n           name: KeyWatch Secret Scanner\n           entry: ./hooks/keywatch.sh\n           language: script\n           files: .*\\.(rs|txt|py|js)$ # Adjust the pattern as necessary\n   ```\n\n4. **Install the pre-commit Hooks:**\n\n   Run the following command to install the hook into your local Git configuration:\n\n   ```sh\n   pre-commit install\n   ```\n\n5. **Test the Integration:**\n\n   To see the hook in action, stage files with potential secrets and try committing:\n\n   ```sh\n   git add \u003cfile-with-secret\u003e\n   git commit -m \"Test commit: should run secret scanner\"\n   ```\n\n   If KeyWatch detects a secret, the commit will be blocked with a detailed error message. Correct the issue (or update your detector configuration) and try committing again.\n\n## Running Tests\n\nKeyWatch comes with integration tests located in the `/tests` directory. To run all tests, execute:\n\n```sh\ncargo test\n```\n\nThis command will run the complete suite of tests ensuring that the scanning and reporting components behave as expected.\n\n## License\n\nKeyWatch is distributed under the terms of the [MIT License](LICENSE), which means you’re free to use and modify the software as long as the license terms are met.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixincreate%2Fkeywatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixincreate%2Fkeywatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixincreate%2Fkeywatch/lists"}