Nosey Parker Documentation

Nosey Parker integrates with several third-party tools and platforms:

• Package Managers: Available via Homebrew and Arch Linux.
• CI/CD: A GitHub Action is available to run Nosey Parker in workflows.
• Vulnerability Management: DefectDojo includes a parser specifically for Nosey Parker v0.16 JSON output.
• Security Tooling: Nemesis supports Nosey Parker.
• Post-processing: noseyparker-compact provides compact report postprocessors.
• Pre-installed Environments: segfault.net disposable root servers come with Nosey Parker preinstalled.

Understanding the Nosey Parker data model is essential for using the tool effectively:

• Datastore: A directory used to record findings and maintain internal state. It is implicitly created by the scan command if it doesn't exist.
• Blob: An individual scanned input (e.g., a file). Each has a unique SHA-1 blob ID.
• Provenance: Metadata describing how a blob was discovered (e.g., a filesystem path or Git history entry).
• Rule: A regular expression with at least one capture group used to isolate secret content.
• Ruleset: A collection of rules (the default ruleset is optimized for secret detection).
• Match: A specific instance where a rule's pattern matches an input, defined by the rule, blob ID, and byte offsets.
• Finding: The top-level unit of reporting. A finding is a group of matches that share the same rule and capture groups (deduplicated matches).

The github repos list command uses the GitHub REST API to list URLs for repositories belonging to a specific user or organization. This is useful for building target lists for scanning.

Set the NP_GITHUB_TOKEN environment variable to improve rate limits.

Example:

$ noseyparker github repos list --user octocat

Use the --format=FORMAT option to output in json or jsonl.

You can scan all accessible repositories for a specific GitHub user or organization using the --github-user or --github-org flags.

To increase API rate limits and access more repositories, set the NP_GITHUB_TOKEN environment variable with a valid GitHub access token.

Example:

$ noseyparker scan --datastore np.noseyparker --github-user octocat

The noseyparker-github-repos command is used to interact with GitHub repositories. It supports various global options for API configuration, output formatting, and performance tuning, and uses subcommands to perform specific tasks like listing repositories.

Basic Usage

noseyparker github repos [options] <subcommand>

Available Subcommands

• noseyparker-github-repos-list: List repositories belonging to a specific user or organization.

To reproduce the usage GIFs shown in the repository, you must use vhs (a console script runner and recording tool) to execute the fragments located in the examples/ directory. The process involves combining individual vhs fragments with common settings via the record-examples.zsh script.

Prerequisites

• Install vhs
• Install noseyparker

Steps

1. Ensure vhs and noseyparker are installed.
2. Run the recording script from the root of the repository:

   ./record-examples.zsh

Generated GIFs will be stored in the gifs/ directory.

Use the scan command to search for secrets in local filesystem content or Git repositories. You can specify a datastore directory with -d or --datastore to save findings.

Note for Docker users: When running in Docker, you must mount your local directory to /scan to use relative paths and enable tab completion:

docker run -v "$PWD":/scan ghcr.io/praetorian-inc/noseyparker:latest <ARGS>

Examples:

Scan a local Git repository:

$ noseyparker scan -d cpython.np cpython.git

Scan a Git repository via HTTPS URL:

$ noseyparker scan --datastore np.noseyparker --git-url https://github.com/praetorian-inc/noseyparker

By default, noseyparker-github uses unauthenticated access. To increase rate limits and access additional content, provide a personal access token by setting the NP_GITHUB_TOKEN environment variable.

Note: This documentation is from version 0.17.0. While the core mechanism of using environment variables for authentication is common in CLI tools, users should verify compatibility with the current version (v0.24.0) as Nosey Parker is officially retired and replaced by Titus.

To create a new datastore, use the init subcommand with the noseyparker datastore command.

Note: This documentation is from version 0.17.0. While the command structure is likely preserved, verify against your current version's help output.

Nosey Parker can be installed via several methods depending on your operating system:

• macOS (Homebrew): brew install noseyparker
• Linux (Prebuilt Binaries): Download from the latest release page (supports x86_64/aarch64).
• Linux (Arch Linux): Available via the AUR.
• Docker:
  • Standard: docker pull ghcr.io/praetorian-inc/noseyparker:latest
  • Alpine base: docker pull ghcr.io/praetorian-inc/noseyparker-alpine:latest
• Windows: Not natively supported, but can be run via WSL1 using the Linux release.

Building from source: Requires cargo, cmake, boost (>=1.57), git, patch, pkg-config, sha256sum, and zsh. Use the provided build script:

$ rm -rf release && ./scripts/create-release.zsh

Artifacts will be located in the release/bin/noseyparker directory.

If you are contributing to the Nosey Parker repository, you can install the enabled pre-commit hooks to detect simple errors locally. Ensure you have pre-commit installed on your system before running the command.

$ pre-commit install