Skip to content

Usage

Jump to bottom
Mick Grove edited this page Aug 11, 2025 · 6 revisions

This page provides detailed examples for scanning each supported target and highlights common options for tailoring scans to your workflow.  

Scanning Git Repositories

Local working directory

Scan the current checkout of a repository:

kingfisher scan /path/to/repo

Entire Git history

Include all commits by enabling the Git history scanner:  

kingfisher scan --git-history /path/to/repo

 

Remote repository URL

Scan a repository without cloning it locally:  

kingfisher scan --git-url https://github.com/org/repo.git

 

Specific branch or commit

Limit the scan to a branch or commit hash:  

kingfisher scan --git-url https://github.com/org/repo.git --git-branch main
kingfisher scan --git-url https://github.com/org/repo.git --git-commit 0123abcd

 

Scanning Hosted Git Services

  Kingfisher can interact with Git hosting providers over their APIs.  

GitHub

  List repositories for a user or organization:  

kingfisher github repos list --user my-user
kingfisher github repos list --organization my-org

  Scan a private repository by passing a token via the KF_GITHUB_TOKEN environment variable:  

KF_GITHUB_TOKEN=ghp_... kingfisher scan --git-url https://github.com/org/private_repo.git

 

GitLab

  Use the GitLab token in KF_GITLAB_TOKEN to scan a project:  

KF_GITLAB_TOKEN=glpat-... kingfisher scan --git-url https://gitlab.com/group/project.git

  List projects within a group:  

kingfisher gitlab projects list --group my-group

 

Scanning S3 Buckets

  Provide AWS credentials with the standard AWS_* environment variables or an --aws-profile value:  

# Scan an entire bucket
kingfisher scan --s3-bucket my-bucket
 
# Scan only a specific prefix within the bucket
kingfisher scan --s3-bucket my-bucket --s3-prefix path/to/folder/
 
# Use a named profile from ~/.aws/credentials
kingfisher scan --s3-bucket my-bucket --aws-profile prod

 

Scanning Docker Images

 

# Scan a local image
kingfisher docker image scan alpine:latest
 
# Scan an image from a remote registry
kingfisher docker image scan ghcr.io/mongodb/kingfisher:latest
 
# Scan a tar archive exported from Docker
kingfisher docker archive scan ./image.tar

 

Scanning Jira Issues

  Authenticate with KF_JIRA_TOKEN and specify the site URL:

Scan Jira issues matching a JQL query

KF_JIRA_TOKEN="token" kingfisher scan \
    --jira-url https://jira.company.com \
    --jql "project = TEST AND status = Open" \
    --max-results 500

*Scan the last 1,000 Jira issues

KF_JIRA_TOKEN="token" kingfisher scan \
  --jira-url https://jira.mongodb.org \
  --jql 'ORDER BY created DESC' \
  --max-results 1000

The --jql flag accepts any Jira Query Language expression, allowing targeted scans across projects or specific issue sets.  

Scanning Slack Messages

  Use a Slack token in KF_SLACK_TOKEN to scan messages:  

# Scan a single channel
KF_SLACK_TOKEN=xoxb-... kingfisher slack channel scan C1234567890
 
# Scan all channels in a workspace
KF_SLACK_TOKEN=xoxb-... kingfisher slack workspace scan

 

Baseline Management

  Generate a baseline file to suppress known secrets and keep only new findings:  

kingfisher scan /src --manage-baseline --baseline-file baseline.yml

  Use the same baseline on future runs to ignore recorded findings:  

kingfisher scan /src --baseline-file baseline.yml

 

List Builtin Rules

 

kingfisher rules list

 

Custom Rules

  Scan using only custom rules:  

kingfisher scan \
--load-builtins=false \
--rules-path path/to/my_rules.yaml \
./src/

  Add your rules alongside the built‑ins:  

kingfisher scan \
--rules-path ./custom-rules/ \
--rules-path my_rules.yml \
~/path/to/project-dir/

  Validate rule definitions before running a scan:  

kingfisher rules check --rules-path ./my_rules.yml

  Example rule file (my_rules.yml):  

- id: custom-api-key
pattern: AKIA[0-9A-Z]{16}
message: "Potential AWS access key"
severity: high

 

Notable Scan Options

 

  • --no-dedup: Report every occurrence of a finding (disable default de-duplication)
  • --confidence <LEVEL>: (low|medium|high)
  • --min-entropy <VAL>: Override default threshold
  • --no-binary: Skip binary files
  • --no-extract-archives: Do not scan inside archives
  • --extraction-depth <N>: Specifies how deep nested archives should be extracted and scanned (default: 2)
  • --redact: Replaces discovered secrets with a one-way hash for secure output
  • --exclude <PATTERN>: Skip any file or directory whose path matches this glob pattern
  • --baseline-file <FILE>: Ignore matches listed in a baseline YAML file
  • --manage-baseline: Create or update the baseline file with current findings
  • --threads <N>: Limit the number of worker threads
  • --output-format <FMT>: Choose human, json, or sarif
  • --max-filesize <BYTES>: Skip files larger than the provided size  

Finding Fingerprint

  The four-field formula (rule SHA-1, origin label, start & end offsets) hashed with XXH3-64 creates Kingfisher's 64-bit finding fingerprint. See docs/FINGERPRINT.md for details.  

Rule Performance Profiling

  Use --rule-stats to collect timing information for every rule. After scanning, the summary prints a Rule Performance Stats section showing how many matches each rule produced along with its slowest and average match times.  

CLI Options

 

kingfisher scan --help
Clone this wiki locally