Skip to content

SSF Toolkit User Guide: analyze credentials Command

Overview

This guide explains how to use the ssf_tools analyze credentials sub-command to detect embedded credentials in files for PCI SSF 2.3 compliance. You will learn how to scan for secrets, customize detection options, and review results in Excel. The tool integrates detect-secrets, which is automatically installed with kp-ssf-tools.

Prerequisites

  • Python 3.13 or later
  • SSF Toolkit installed
  • Access to files or directories to analyze

Quick Start

To scan a file for embedded credentials, run:

ssf_tools analyze credentials sample.py

To view all available options:

ssf_tools analyze credentials --help

Usage

The analyze credentials command scans files and directories for hard-coded secrets such as passwords, API keys, and tokens. Results are exported to Excel, with per-file worksheets and a summary sheet for easy review.

Common Commands

  • ssf_tools analyze credentials <target>: Scan a file or directory for credentials
  • ssf_tools analyze credentials src/ --file-extensions .py --no-recursive: Scan only Python files in a directory, non-recursively

Workflow

  1. Run the Analysis
  2. Execute the command with your desired options: 
    ssf_tools analyze credentials <target> [options]
  3. The tool displays progress and summary information in the terminal.

  4. Results are saved to an Excel file named analyze-credentials-<timestamp>.xlsx in your working directory.

  5. Open the Excel Results

  6. Locate the generated Excel file.

  7. Open it in Microsoft Excel or a compatible spreadsheet application.

  8. Review the Findings

  9. Each worksheet corresponds to a scanned file; the summary sheet aggregates results.
  10. Columns include file name, line number, secret type, context lines, and match details.

  11. Use Excel's filtering and sorting features to focus on high-risk findings.

  12. Interpret and Act

  13. Investigate matches flagged as credentials or secrets.
  14. Use context lines to understand the surrounding code or data.
  15. Share or archive the Excel file for compliance documentation or further analysis.

Tips

  • Use file extension filters to focus on relevant file types.
  • Increase context lines for more code around each match.
  • For large projects, consider disabling binary scanning to improve performance.
  • See additional tuning considerations below.

Configuration

You can customize the credential detection using the following options:

Option Description
--recursive/--no-recursive Search directories recursively for files to analyze (default=recursive
--file-extensions File extensions to include (e.g., .py, .js, .txt). If not specified, all text files are analyzed
--context-lines Number of context lines to show around matches (default=3)
--scan-binary/--no-scan-binary Whether to scan binary files for embedded credentials
--max-binary-size Maximum size in MB for binary files to scan (default=10)
--help / -h Show help message and exit

Tuning

  • Use --file-extensions to limit scanning to specific file types and reduce noise.
  • Adjust --context-lines to see more or less surrounding code for each match.
  • Disable binary scanning with --no-scan-binary for faster results in source code repositories.
  • Increase --max-binary-size if you expect large binaries to contain secrets.

Example: Customizing Analysis

ssf_tools analyze credentials src/ --file-extensions .py --context-lines 5 --no-scan-binary --no-recursive

This command scans only Python files in the src/ directory, shows five lines of context around each match, skips binary files, and disables recursion.

Example: Scanning All Files Recursively

ssf_tools analyze credentials project/ --recursive

This command scans all supported files in the project/ directory and subdirectories for embedded credentials.

Advanced Features

  • Exports results to Excel with per-file worksheets and a summary sheet
  • Integrates detect-secrets for robust secret detection
  • Supports verbose output for detailed progress

Troubleshooting

  • If no files are found, check your target path and file extension filters
  • For Excel export issues, review file size and worksheet limits
  • Use verbose mode for more detailed output

FAQ

  • Q: How do I scan only JavaScript files? A: Use --file-extensions .js.
  • Q: Can I see more code around each match? A: Yes, increase --context-lines.
  • Q: What is detect-secrets? A: It is an open-source tool for finding secrets in code, included with SSF Toolkit.

Additional Resources

Use this guide to get started with credential detection. Adjust options as needed for your workflow and refer to other guides for advanced topics.