testssl.sh Output Formats: JSON, CSV, and HTML Options Explained

testssl.sh supports three machine-readable output formats—JSON (flat and structured), CSV, and HTML—controlled via command-line flags like --json, --csv, and --html that write findings to timestamped files.

The SSL/TLS testing tool testssl.sh (available at drwetter/testssl.sh) generates comprehensive security audit reports. Beyond terminal output, the script can serialize findings into structured formats suitable for automation, archival, or sharing with stakeholders.

Overview of testssl.sh Output Formats

According to the source code in testssl.sh (lines 21624–21634), the tool provides dedicated options for each output type. These options can also be preset via environment variables.

JSON Output (Flat and Pretty)

testssl.sh offers two JSON serialization styles:

• --json: Writes flat JSON where each check appears as a single-line object without a global header. This format is ideal for line-by-line processing and log aggregation.
• --json-pretty (or --jsonfile-pretty): Writes structured JSON with a metadata header containing command-line arguments, version information, and timestamps, followed by nested test sections. This is easier for human review and tools consuming full documents.

By default, JSON files follow the naming pattern ${NODE}-p${port}${YYYYMMDD-HHMM}.json in the current working directory.

CSV Output

The --csv option mirrors the flat JSON fields in a comma-separated table. This format is optimized for spreadsheet analysis and statistical processing of SSL/TLS findings.

Default filename pattern: ${NODE}-p${port}${YYYYMMDD-HHMM}.csv.

HTML Output

The --html option generates a web-ready report using the template defined in doc/template.html. This reproduces the console color scheme and layout in a browser-friendly format, making it convenient for sharing results with non-technical stakeholders.

Default filename pattern: ${NODE}-p${port}${YYYYMMDD-HHMM}.html.

How to Use testssl.sh Output Format Options

Each format supports both automatic filename generation and explicit file path specification.

Basic Usage Examples

Generate a flat JSON file with the default timestamped name:

testssl.sh --json example.com:443

Create a structured (pretty) JSON report at a specific path:

testssl.sh --jsonfile-pretty /tmp/audit-report.json example.com:443

Write CSV output to a directory (the script creates the timestamped filename inside that folder):

testssl.sh --csvfile ./results example.com:443

Generate an HTML report with a custom filename:

testssl.sh --htmlfile security-scan.html example.com:443

Combining Multiple Formats

You can export to several formats in a single execution by combining flags:

testssl.sh \
    --jsonfile-pretty json/scan.json \
    --csvfile csv/scan.csv \
    --htmlfile html/scan.html \
    example.com:443

Note: Use --append to concatenate new results to an existing file without writing a new header, or --overwrite to force replacement of existing files.

Source Code Implementation

The output format logic is implemented in the main script testssl.sh. The command-line parsing occurs around lines 21627–21634, where options like --jsonfile <jsonfile>, --csvfile|-oC <csvfile>, and --htmlfile|-oH <htmlfile> are defined.

The manual page in doc/testssl.1.md (lines 319–333) documents these options, explaining that --jsonfile and --jsonfile-pretty accept either a filename or directory path, similar to --logfile.

For HTML generation, the script utilizes doc/template.html as the structural backbone for the generated reports. The test suite in the t/ directory validates format correctness through files like t/31_isJSON_valid.t, t/32_isHTML_valid.t, and t/33_isCSV_valid.t.

Summary

• testssl.sh supports JSON (flat and pretty), CSV, and HTML output formats via command-line flags.
• Flat JSON (--json) outputs line-by-line objects for streaming parsers; pretty JSON (--json-pretty) includes metadata headers for document-style consumption.
• CSV (--csv) provides spreadsheet-compatible tabular data.
• HTML (--html) renders browser-friendly reports using the template in doc/template.html.
• All formats support custom paths via --jsonfile, --csvfile, and --htmlfile, or default to timestamped filenames in the current directory.

Frequently Asked Questions

What is the difference between --json and --json-pretty in testssl.sh?

--json produces flat JSON where each finding is a separate JSON object on its own line, optimized for log processing and line-based tools. --json-pretty generates structured JSON with a header object containing scan metadata (timestamp, version, command line) followed by nested test results, which is easier for human reading and full-document parsing.

Can I generate multiple output formats in a single testssl.sh scan?

Yes. You can combine output flags in one command, such as testssl.sh --jsonfile-pretty report.json --csvfile report.csv --htmlfile report.html example.com. This runs the scan once and writes findings to all three specified files simultaneously.

How do I specify a custom filename or directory for testssl.sh reports?

Use the file-specific variants: --jsonfile <path>, --csvfile <path>, or --htmlfile <path>. If you provide a directory path, testssl.sh creates the file using the standard naming pattern ${NODE}-p${port}${YYYYMMDD-HHMM} inside that directory. If you provide a file path, it writes directly to that location.

Does testssl.sh append to existing files or overwrite them?

By default, testssl.sh checks for file existence and prompts for action. Use --append to concatenate new results to an existing file (omitting headers on subsequent writes), or --overwrite to force deletion and recreation of the output file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}