Blackbox Exporter
An open-source endpoint probing tool, written in Go. It probes HTTP, DNS, TCP, ICMP and WebSocket targets on demand and exposes the results as Prometheus metrics. Maintained by the Prometheus project.
Business rules, traced to source lines.
These 12 rules are a sample of the 636 CoreStory V3 extracted from Blackbox Exporter. Each one links to the exact lines on GitHub at commit 655fd77. The statement is CoreStory V3’s wording; the code excerpt is the source it cites.
If ValidStatusCodes is non-empty, success is true only when the response status code is in the list; otherwise an error is logged. If ValidStatusCodes is empty, success requires the status code in [200, 300).
- 200 — inclusive lower bound for default 2xx success range
- 300 — exclusive upper bound for default 2xx success range
Redirects are followed only if FollowRedirects is true and the redirect count (len(via)) is at most 10; otherwise an error is returned to stop following.
- 10 — maximum number of redirects allowed
If BodySizeLimit is greater than 0, the response body is wrapped in http.MaxBytesReader with that limit (applied after decompression if applicable).
- 0 — threshold above which BodySizeLimit is enforced
If FailIfBodyJSONMatchesCEL is configured, the CEL expression is evaluated against a payload containing the JSON-parsed response body under key body. The probe fails if evaluation errors, if the result type is not boolean, or if the boolean result is true.
- body — key under which parsed JSON body is exposed to CEL expressions
Also cited: L85–L87
If no list of valid rcodes is specified, only the DNS rcode NOERROR is considered valid; if a list is specified, each entry must be a known DNS rcode name and the response rcode must be contained in the resulting list.
- NOERROR — default valid rcode name
Also cited: L117–L122
When DNS over TLS is enabled, the transport protocol must be tcp; if it is not tcp, the probe fails.
- tcp — required transport protocol for DNS over TLS
The effective timeout is the module's configured timeout when the module timeout is greater than 0 seconds and less than `maxTimeoutSeconds` (the header timeout minus the offset), or when `maxTimeoutSeconds` is negative; otherwise the effective timeout is `maxTimeoutSeconds`.
If the requested module name is not present in the configuration's Modules map, the request is rejected with HTTP 400 Bad Request and the unknown-module counter (if non-nil) is incremented by 1.
- 400 — HTTP status code returned
- 1 — increment applied to the unknown-module counter
After appending a result, if the number of results exceeds rh.MaxResults, the oldest result is removed, so rh.results retains at most rh.MaxResults entries.
The /logs endpoint rejects a request with both a probe id and a target as HTTP 400 with the message that probe id and target cannot be defined at the same time.
- 400 — HTTP status code for conflicting parameters
Also cited: L243–L247
The last chain expiry is the latest among the earliest non-zero NotAfter values of each verified chain; within a chain, a certificate's NotAfter replaces the earliest chain expiry when the chain expiry is zero or the certificate's NotAfter is before it, and the certificate's NotAfter is not zero.
Also cited: L56–L71
For each query response with a configured Expect.Regexp, lines are scanned until one matches the regexp. If reading from the connection errors, the probe returns false. If no line matches, probe_failed_due_to_regex is set to 1, an error is logged, and the probe returns false. If a match is found, probe_failed_due_to_regex is reset to 0.
- 1 — failure indicator set when regexp does not match
- 0 — failure indicator reset when regexp matches
Also cited: L67–L70
What the application does
15 capabilities identified, grouping the 104 distinct features extracted. These are descriptions, not the cited rules above.
HTTP Probing and Response Assertions
Executes configurable HTTP/HTTPS requests and validates status, headers, body, redirects, encoding, and protocol versions.
- Configurable HTTP Probing: Runs HTTP health probes with configurable HTTP method and request timeout.
- Content-Encoding Validation: Validates the compression content encodings accepted for a connection.
- Cookie Jar Support: Maintains cookies across HTTP requests during probing.
- HTTP Endpoint Probing: Probe HTTP/HTTPS endpoints and assert on status codes, headers, body, or OAuth2-authenticated responses.
- HTTP Header Configuration: Lets a user define custom HTTP headers for outgoing requests.
- HTTP Probe: Probe an HTTP endpoint and return its response for health or availability checks.
- HTTP Probe Monitoring: Executes HTTP/HTTPS probes against targets to validate reachability, status codes, and protocol behavior.
- HTTP Probing: A capability that performs HTTP requests and validates responses against configurable rules, timeouts, and headers.
- HTTP Redirect Handling: Controls whether and how far HTTP redirects are followed during probing.
- HTTP Request Execution: Issue HTTP requests with custom headers, bodies, gzip compression, and proxy support.
- HTTP Request Tracing: Emit trace events across the lifecycle of an HTTP request, from DNS through connection, TLS, and first response byte.
- HTTP Version Negotiation: Allows a user to select and validate the HTTP protocol versions (HTTP/2, HTTP/3) used for requests.
- HTTP/3 QUIC Probing: Performs HTTP/3 over QUIC probes including scheme and version handling.
- Header and Response Matching: Matches HTTP headers and DNS response records against configured criteria.
- Query Response Matching: Probes that send a query and match the peer's response bytes against expected patterns, including byte-mode responses.
- Query Response Probing: Probes and queries HTTP responses to inspect their information and behavior.
- Response Body Reading: Read and stream the HTTP response body, applying content decompression.
- Response Content Assertions: Validates response bodies and headers against regexp and CEL match conditions.
TLS and Certificate Management
Establishes and inspects TLS/StartTLS connections, validates certificate chains, and generates and revokes X.509 certificates.
- Certificate Chain Probing: Probes certificate chains against a target (CAS and leaf subjects) to evaluate trust and revocation state.
- Certificate Revocation Check: Verify that presented certificates have not been revoked.
- Certificate Revocation List (CRL) Management: Creation of certificate revocation lists and the hosting of a CRL distribution server with TLS.
- Protocol Negotiation Testing: Testing of negotiated TLS protocol selection against a configured chain state.
- SSL Certificate Expiry Monitoring: Measures and exposes when a target's TLS certificates expire or were earliest valid.
- StartTLS Upgrade Probing: Probes that negotiate a StartTLS upgrade on a TCP connection, optionally validating the presented certificate chain and CRL.
- TCP over TLS Connection: Establish a TCP connection secured with TLS, supporting an optional CA or CA file for certificate verification.
- TLS / StartTLS Connection Upgrade: Determines whether encrypted transport (StartTLS) should be used for a connection.
- TLS Certificate Inspection: Retrieving and exposing TLS certificate details—subject, issuer, serial number, fingerprint, DNS names, and expiry timings—for a probed endpoint.
- TLS Certificate Validation: Checks SSL/TLS certificate conditions such as self-signed CAs and CRL availability.
- TLS Connection: Establish and probe TLS connections to remote endpoints.
- TLS Connection Parameters: Exposing the negotiated TLS version and cipher suite of a probed connection.
- TLS Handshake Verification: Perform TLS handshakes with configurable CA, certificates, and revocation checking.
- TLS Probing: Performs TLS handshake probes to inspect a target's TLS configuration.
- TLS Serial Number Retrieval: Retrieval of the serial number from a TLS connection for certificate identification.
- X.509 Certificate Generation: Generation of X.509 certificates, including self-signed, signed, and template-based certificates with private keys.
- gRPC TLS Security: Secure gRPC connections using TLS and certificate revocation list verification, with detection of absent or failed TLS.
Network Service Probing
Cross-cutting capability to probe reachability and availability of services across HTTP, TCP/UDP, ICMP, Unix sockets, DNS, gRPC, and WebSocket transports.
- Connection Probing: Probe a connection with a configurable timeout to test reachability.
- ICMP Ping: Send ICMP echo requests to verify host reachability and IP protocol behavior.
- ICMP Probe: Sends ICMP echo requests to hosts, generating and tracking ICMP identifiers and sequences for the probes.
- Network Prober: Provides a configurable probe with timeout and preferred IP protocol for network requests.
- Network Service Probing: A capability that tests reachability and availability of network services and endpoints across protocols such as TCP, ICMP, and HTTP.
- Probe Definitions: Defines the probe types users configure to check targets over HTTP, TCP, ICMP, gRPC, DNS, Unix sockets, and WebSockets.
- Probe Expectation Verification: Probes whose observed outcomes are verified against expected probe success/failure information.
- TCP Connection Probing: Active TCP connection probes against targets over plain TCP, TLS, and StartTLS transports to observe reachability and protocol handshake behaviour.
- TCP Connectivity Probe: Establishes and verifies TCP connectivity to a target endpoint on behalf of a caller.
- TCP Port Probing: Establish raw TCP connections to a host and port to verify reachability.
- TCP and UDP Connectivity: Connect to TCP and UDP endpoints, including Unix domain socket pings and raw TCP connects.
- Unix Socket Connectivity Probing: Probes and establishes connectivity to a target over Unix domain sockets.
- Unix Socket Probing: Connect to Unix domain sockets and assert on expected byte sequences.
DNS Resolution and Serving
Resolves DNS queries authoritatively and recursively, supports multiple transports including DNS over HTTPS, and reports DNS metrics.
- Authoritative DNS Resolution: Serves authoritative DNS answers to clients for the hosted zones.
- DNS Metrics Reporting: Exposes operational DNS metrics that users or monitoring systems can observe.
- DNS Probing: Probes DNS servers and validates their responses (resource records, response codes) to assess availability and correctness.
- DNS Protocol Support: Handles DNS queries across the supported transport protocols.
- DNS Query Probing: Resolve DNS names and validate the returned answer resource records.
- DNS Server Startup: Starts the DNS server and dispatches queries over supported protocols.
- DNS over HTTPS: Perform DNS lookups over HTTPS in JSON and wireformat encodings, exposed via an SOA data structure.
- Recursive DNS Resolution: Resolves client queries by recursing to upstream DNS servers, including servfail handling.
HTTP Authentication
Authenticates outbound HTTP and WebSocket probes using basic, bearer, OAuth2 client-credentials, JWT, and mTLS schemes.
- Basic Authentication: Supply username/password credentials to authenticate probe requests.
- Bearer Token Authentication: Authenticates HTTP probes using an inline bearer token or a token loaded from a file.
- HTTP Authentication: Authenticate HTTP requests using Basic auth, OAuth client-credentials, JWT bearer, and mTLS schemes.
- HTTP Basic Authentication: Authenticates HTTP probes using a configured username and password via basic auth.
- JWT Bearer Claim Validation: Validate JWT bearer tokens against expected issuer, audience, and subject claims.
- OAuth2 Client Credential Configuration: Users configure OAuth2 client credentials — including a JWT bearer key or key file, client certificate, and client id — to authenticate with a token endpoint.
- OAuth2 Token Acquisition: Obtain access tokens using configurable OAuth2 grant types and client credentials.
- WebSocket Connectivity: Connect to WebSocket endpoints using Basic auth or bearer token credentials.
Response Matching and Expression Validation
Matches probe responses against regexp, CEL expressions, headers, JSON, and metric assertions.
- CEL Expression Evaluation: Compiles and evaluates CEL expressions used to validate probe responses.
- Custom CA and JSON Response Matching: Trust a custom CA for HTTP checks and assert responses using JSON/CEL matching.
- Header and Response Matching: Matches HTTP headers and DNS response records against configured criteria.
- Metric Validation and Assertion: Validation of metrics and their labels/values, including checks for absent metrics and registry results.
- Query Response Matching: Probes that send a query and match the peer's response bytes against expected patterns, including byte-mode responses.
- Regular Expression Matching: Compiles and exposes regular expressions used for matching responses.
- Request Filtering and Matching: Match requests against CEL expressions and regular expressions, including header-based matching.
- Response Content Assertions: Validates response bodies and headers against regexp and CEL match conditions.
CI Automation and Stale Issue Management
Automates build, lint, and test pipelines and schedules closing of stale issues and pull requests with exemptions and thresholds.
- CI Workflow Pipeline: A configurable jobs pipeline with triggers and permissions that builds, publishes, and tests artifacts automatically.
- Close Stale Issues and Pull Requests: Marks and closes issues and pull requests that have been inactive past a configured threshold.
- Continuous Integration Lint Job: A CI job that installs Go, lints the codebase with golangci-lint, and checks the repository.
- Exempt Items from Staling: Allows specific items to be excluded from stale processing via label exemptions.
- Scheduled Stale Automation: Runs the stale management on a recurring schedule or via manual dispatch.
- Separate PR Stale Threshold: Configures a distinct inactivity window before pull requests are considered stale.
- Workflow Token and Permissions: Grants the automation a repo token and required permissions to act on issues and PRs.
Service Banner and Application Protocol Probing
Connects to service ports to capture greeting banners and speaks application protocols such as IRC and WebSocket to verify availability.
- Application Protocol Checking: A capability that verifies availability of higher-level application protocols including gRPC, WebSocket, and PostgreSQL.
- IRC Banner Check: Connect to an IRC server and observe its banner response.
- IRC Protocol Probing: Probes that speak the IRC protocol over a TCP connection and report the observed query responses.
- Message Broker and Database Probes: Probe RabbitMQ (secure and insecure) and PostgreSQL endpoints.
- Service Banner Grabbing: A capability that connects to service ports and extracts identifying banner information to fingerprint running services.
- WebSocket Connectivity: Connect to WebSocket endpoints using Basic auth or bearer token credentials.
- Websocket Connectivity Probe: A capability that probes websocket endpoints using configured headers and matches responses against query patterns.
Certificate Revocation Checking
Fetches, manages, and validates certificate revocation lists to determine whether certificates have been revoked.
- CRL Chain Validation: Validates CRL (certificate revocation list) chains, including via a proxy and with intermediate CAs, to determine certificate revocation status.
- CRL Fetching: Retrieves certificate revocation lists over HTTP from configured CRL URLs for use in revocation checks.
- CRL Metrics Export: Emits telemetry metrics about CRL fetching and revocation checks for monitoring.
- CRL Metrics Registration: Registers CRL-related metrics with a URL label for observability of CRL operations.
- CRL Revocation Check: Checks certificates against certificate revocation lists to determine whether a certificate has been revoked.
- Certificate Revocation Check: Verify that presented certificates have not been revoked.
Configuration Management
Loads, versions, and hot-reloads application settings and probe definitions, including quality tooling such as formatting and linting.
- Code Formatting: Configures formatting options such as gofumpt, goimports, local-prefixes, and presets.
- Code Linting: Configures linting behavior and exclusion rules for analyzed code.
- Configuration Loading and Hot Reload: Loads the application configuration and supports reloading it at runtime via SafeConfig/NewSafeConfig/ReloadConfig.
- Path Filtering: Limits analysis to specified paths and group parameters.
- Settings Management: Enables, configures, and versions the tool's settings.
Observability and Metrics Export
Exposes operational metrics for tracking timeouts, CRL operations, DNS, and probe outcomes for monitoring systems.
- CRL Metrics Export: Emits telemetry metrics about CRL fetching and revocation checks for monitoring.
- CRL Metrics Registration: Registers CRL-related metrics with a URL label for observability of CRL operations.
- DNS Metrics Reporting: Exposes operational DNS metrics that users or monitoring systems can observe.
- Metric Validation and Assertion: Validation of metrics and their labels/values, including checks for absent metrics and registry results.
- Prometheus Timeout Probing: Probes that exercise timeout behaviour against targets and expose the outcome for Prometheus scraping.
gRPC Probing
Establishes gRPC connections with metadata, TLS, and revocation checks, and probes service health.
- gRPC Connection: Establishing and managing gRPC client connections, including plain and multi-service connectivity.
- gRPC Health Check: Invoke the gRPC health service to determine service liveness.
- gRPC Health Checking: A gRPC health checking capability that creates a health check client and probes service health over gRPC.
- gRPC Metadata: Passing request metadata along with gRPC calls.
- gRPC TLS Security: Secure gRPC connections using TLS and certificate revocation list verification, with detection of absent or failed TLS.
Conformance History and Result Tracking
Stores, preserves, and looks up conformance test results and query history with configurable retention.
- Conformance History Lookup: Retrieves stored conformance history entries by ID, target, or target and module.
- Conformance History Storage: Persists and retains conformance test run results with configurable retention of successes and failures.
- Failed Result Preservation: Retains failed results so they are not lost across operations.
- Result History Tracking: Maintains a queryable history of results with lookup by ID or by target and module, plus paged listing.
Container Image Build and Publishing
Builds container images with entrypoints and publishes project documentation to container registries.
- Container Image Build: Builds a container image from source, including repository checkout, Go build with linker flags, and tarball packing.
- Container Image Entrypoint Execution: A container image is configured to launch a specified command when started, with architecture and OS metadata selecting the appropriate container base.
- Registry README Publication: Push a project's README documentation to container image registries such as Docker Hub and Quay.io so it is displayed on the registry listing.
External URL Resolution
Computes publicly-facing URLs for resources so other systems can determine external addresses.
- External URL Computation: Computes the externally-visible URL for a resource, a capability relied on by other systems to determine public-facing addresses.
What was analyzed
- Go · 30 files · 9,262 lines
- YAML · 42 files · 1,220 lines
- Markdown · 11 files · 958 lines
- Dockerfile · 2 files · 39 lines
- make · 1 file · 2 lines
Whole repository: 95 files. cloc 2.06 counts 11,481 lines of code in 86 of them (13,996 lines with comments and blanks).
Where this came from
Extracted by CoreStory V3 (build 4470 with two small engine fixes) using DeepSeek-V4.1-Flash from the public repository at commit 655fd77 on 2026-11-13. Capability descriptions are from the same run.
- Repository prometheus/blackbox_exporter
- Commit 655fd7785bd2921b436c7b9e829e4c0dc4586259
- Line counts cloc 2.06
- Rule citations Each rule shown was checked: its quote was compared with the repository source at the cited lines at this commit.
Code excerpts are from the upstream repository and remain under its Apache-2.0 license. CoreStory is not affiliated with or endorsed by the Prometheus project.
Want this for your own codebase?
Talk to us about mapping the business rules in your repositories.