186 lines
7.0 KiB
Markdown
186 lines
7.0 KiB
Markdown
# SSL Certificate Checker
|
|
|
|
This project is a command-line tool written in Go that checks the validity and expiration of an SSL/TLS certificate for a given host and port. It is a lightweight utility that can be used to monitor the SSL status of your services and ensure timely renewal of certificates.
|
|
|
|
## Overview
|
|
|
|
The tool connects to a specified host and port using TLS, verifies the provided hostname against the certificate, and checks the expiration date of the certificate. It provides warnings or critical alerts based on configurable thresholds for days remaining until expiration.
|
|
|
|
## Features
|
|
|
|
- **Hostname Verification**: Verifies that the hostname matches the certificate.
|
|
- **Certificate Expiration Check**: Checks how many days are left until the SSL/TLS certificate expires.
|
|
- **Configurable Alerts**:
|
|
- **Warning**: Triggered when the remaining validity is below a specified number of days.
|
|
- **Critical**: Triggered when the certificate is on the brink of expiration or has already expired.
|
|
- **Customizable Parameters**: Command-line arguments let you tailor the behavior to specific needs (e.g., host, port, thresholds, timeouts).
|
|
|
|
## Usage
|
|
|
|
Run the program using the command line with the following syntax:
|
|
|
|
```bash
|
|
./ssl-checker -H <hostname> [-p <port>] [-w <warning days>] [-c <critical days>] [-t <timeout>]
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Description | Default Value |
|
|
|---------------|------------------------------------------------------------------------------------------|---------------|
|
|
| `-H <host>` | The hostname to check (required). | None |
|
|
| `-p <port>` | The port to connect to. Typically `443` for HTTPS. | `443` |
|
|
| `-w <days>` | Warning threshold in days. Issues a warning if certificate expiration is below this threshold. | `30` |
|
|
| `-c <days>` | Critical threshold in days. Fails critically if expiration is below this threshold. | `15` |
|
|
| `-t <ms>` | Connection timeout in milliseconds. | `1000` |
|
|
|
|
### Example Usage
|
|
|
|
#### Check an SSL certificate for `example.com`:
|
|
```bash
|
|
./ssl-checker -H example.com
|
|
```
|
|
|
|
#### Check an SSL certificate for `example.com` on a custom port `8443`:
|
|
```bash
|
|
./ssl-checker -H example.com -p 8443
|
|
```
|
|
|
|
#### Set a custom warning threshold of 20 days and critical threshold of 10 days:
|
|
```bash
|
|
./ssl-checker -H example.com -w 20 -c 10
|
|
```
|
|
|
|
#### Specify a timeout of 2000 milliseconds:
|
|
```bash
|
|
./ssl-checker -H example.com -t 2000
|
|
```
|
|
|
|
## Creating a Statically Linked Binary
|
|
|
|
To build a statically linked binary, follow the steps below:
|
|
|
|
### Step 1: Set the Environment Variable
|
|
Disabling `cgo` ensures that the binary is fully statically linked.
|
|
|
|
```bash
|
|
CGO_ENABLED=0 go build -o ssl-checker main.go
|
|
```
|
|
|
|
### Step 2: Cross-Compiling for Other Platforms (Optional)
|
|
You can build the binary for another platform by setting the `GOOS` and `GOARCH` environment variables:
|
|
|
|
For Linux:
|
|
```bash
|
|
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o ssl-checker main.go
|
|
```
|
|
|
|
For Windows:
|
|
```bash
|
|
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o ssl-checker.exe main.go
|
|
```
|
|
|
|
To build a smaller binary, include the `-ldflags="-s -w"` flag when building (as shown below).
|
|
|
|
## Creating a Minimal Stripped Build
|
|
|
|
To minimize binary size, you can strip unnecessary debugging and symbol information during the build process.
|
|
|
|
### Step 1: Build a Stripped Binary
|
|
```bash
|
|
go build -ldflags="-s -w" -o ssl-checker main.go
|
|
```
|
|
|
|
- `-s`: Strips the symbol table from the binary (reduces size).
|
|
- `-w`: Strips the debugging information from the binary (further reduces size).
|
|
|
|
### Step 2: Compress the Binary with UPX
|
|
[UPX](https://upx.github.io/) can further reduce the file size of the binary. After building the binary, use UPX as follows:
|
|
|
|
1. Install UPX:
|
|
```bash
|
|
sudo apt install upx
|
|
```
|
|
or download it from the [UPX website](https://upx.github.io/).
|
|
|
|
2. Compress the binary:
|
|
```bash
|
|
upx --best --lzma -o ssl-checker-compressed ssl-checker
|
|
```
|
|
|
|
- `--best`: Ensures the highest compression ratio.
|
|
- `--lzma`: Uses the LZMA algorithm for optimal compression.
|
|
- `-o ssl-checker-compressed`: Specifies the name of the compressed output binary.
|
|
|
|
Execution time: compressed vs uncompressed:
|
|
```bash
|
|
time ./ssl-checker-compressed
|
|
Usage: -H <hostname> [-p <port>] [-w <warning days>] [-c <critical days>] [-t <timeout>]
|
|
|
|
________________________________________________________
|
|
Executed in 74.73 millis fish external
|
|
usr time 71.91 millis 229.00 micros 71.68 millis
|
|
sys time 3.10 millis 118.00 micros 2.99 millis
|
|
|
|
```
|
|
```bash
|
|
time ./ssl-checker
|
|
Usage: -H <hostname> [-p <port>] [-w <warning days>] [-c <critical days>] [-t <timeout>]
|
|
|
|
________________________________________________________
|
|
Executed in 2.04 millis fish external
|
|
usr time 0.22 millis 216.00 micros 0.00 millis
|
|
sys time 2.02 millis 112.00 micros 1.91 millis
|
|
```
|
|
|
|
### Verifying the Binary is Statically Linked
|
|
On Linux, confirm the binary is statically linked by checking its dependencies:
|
|
```bash
|
|
ldd ./ssl-checker
|
|
```
|
|
|
|
If it is statically linked, the result will show:
|
|
|
|
```bash
|
|
not a dynamic executable
|
|
```
|
|
|
|
## Outputs and Exit Codes
|
|
|
|
The tool provides output and exit codes for various scenarios:
|
|
|
|
| Status | Output | Exit Code |
|
|
|--------------------------------------|---------------------------------------------------------------|-----------|
|
|
| Certificate is valid and not expiring soon. | `OK: Certificate for <host> is valid, expires in <days> days.` | `0` |
|
|
| Certificate is nearing expiration. | `WARNING: Certificate for <host> expires in <days> days.` | `1` |
|
|
| Certificate is expired or critically close to expiration. | `CRITICAL: Certificate for <host> expired <days> days ago.` or `CRITICAL: Certificate for <host> expires in <days> days.` | `2` |
|
|
| Hostname verification failed. | `CRITICAL: Hostname verification failed for <host>.` | `2` |
|
|
| Connection error. | `CRITICAL: Could not connect to <host>:<port>.` | `2` |
|
|
|
|
## Notes
|
|
|
|
- Statically linked builds are highly portable and do not depend on system libraries (useful for deploying on minimalist systems).
|
|
- UPX-compressed files may increase memory usage during decompression, so use them where size is critical.
|
|
|
|
## Building from Source
|
|
|
|
To build the tool, ensure you have Go installed and follow these steps:
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd <repository-dir>
|
|
```
|
|
|
|
2. Build the binary:
|
|
```bash
|
|
go build -o ssl-checker main.go
|
|
```
|
|
|
|
3. Run the tool:
|
|
```bash
|
|
./ssl-checker -H example.com
|
|
```
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. See the `LICENSE` file for details. |