KeyMon is a modular, plugin-based command-line tool that extracts SSL certificate information from various sources and uploads them to your SSL Guardian dashboard for monitoring and management.

🔌 Plugin Architecture

KeyMon uses a modular plugin system that makes it easy to collect certificates from any source. Each plugin handles a specific certificate source with its own parameters and logic.

Core Plugins

domain - Live HTTPS domain scanning
keystore - Java keystores (.jks, .p12, .pfx)
cert-folder - Certificate file directories
pki-bundle - PKI CA bundles

Extended Plugins

k8s-secrets - Kubernetes TLS secrets
nginx - Nginx configuration files
aws-acm - AWS Certificate Manager
azure-keyvault - Azure Key Vault
macos-keychain - macOS Keychain
postgres-tls - PostgreSQL TLS certificates
windows-certstore - Windows Certificate Store

Features

🔌 Modular Plugin System - Extensible architecture for any certificate source
🔄 Backward Compatibility - Legacy syntax still works
🏷️ Environment Tagging - Tag certificates with environment and group metadata
📊 Certificate Management - List, filter, and delete certificates
⏰ Cron Job Scheduling - Automated certificate collection
🔒 Secure Authentication - Token-based authentication
🚀 Easy Extension - Add new plugins without touching core code

Prerequisites

Required

Node.js (v14 or higher)
OpenSSL - For certificate file and PKI bundle parsing
SSL Guardian Team or Enterprise Account - With a valid token

Optional

OpenSSL - Required only for some certificate file parsing (fallback for complex formats)

Installation

NPM Package (Recommended)

npm install -g keymon
keymon --list-plugins

From Source

git clone https://github.com/ssl-guardian/keymon.git
cd keymon
chmod +x collectorjs
./collectorjs --list-plugins

Authentication Setup

Get Your Organization ID (org_id) and Token:
- Login to SSL Guardian
- Go to Settings → Tokens
- Get your org_id and create a new token and copy those values.
Set Environment Variables (recommended):

export SSL_GUARDIAN_TOKEN="your_token_here"
export SSL_GUARDIAN_ORG_ID="your_org_id_here"
export SSL_GUARDIAN_API_URL="https://app.sslguardian.io"  # Optional

Usage

Plugin-Based Usage (Recommended)

Domain Scanning:

keymon --plugin domain --domains example.com --token YOUR_TOKEN --org-id YOUR_ORG_ID
# or from source: ./collectorjs --plugin domain --domains example.com --token YOUR_TOKEN --org-id YOUR_ORG_ID
keymon --plugin domain --domains "example.com,api.example.com,www.example.com"

Java Keystore:

keymon --plugin keystore --keystores /path/to/keystore.jks --token YOUR_TOKEN --org-id YOUR_ORG_ID
keymon --plugin keystore --keystores /path/to/keystore.jks --password mypassword

Certificate Folder:

keymon --plugin cert-folder --folders /etc/ssl/certs/ --token YOUR_TOKEN --org-id YOUR_ORG_ID

PKI CA Bundle:

keymon --plugin pki-bundle --bundles /etc/ssl/internal-ca.pem \
  --environment production --group "Internal Services" --token YOUR_TOKEN --org-id YOUR_ORG_ID

Kubernetes Secrets:

keymon --plugin k8s-secrets --namespace prod --token YOUR_TOKEN --org-id YOUR_ORG_ID
keymon --plugin k8s-secrets --kubeconfig /path/to/config --namespace default

Nginx Configuration:

keymon --plugin nginx --config-path /etc/nginx/sites-enabled/ --token YOUR_TOKEN --org-id YOUR_ORG_ID

AWS Certificate Manager:

keymon --plugin aws-acm --region us-east-1 \
  --access-key-id YOUR_ACCESS_KEY --secret-access-key YOUR_SECRET_KEY \
  --token YOUR_TOKEN --org-id YOUR_ORG_ID

Azure Key Vault:

keymon --plugin azure-keyvault --vault-name myvault \
  --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --tenant-id YOUR_TENANT_ID \
  --token YOUR_TOKEN --org-id YOUR_ORG_ID

macOS Keychain:

keymon --plugin macos-keychain --token YOUR_TOKEN --org-id YOUR_ORG_ID
keymon --plugin macos-keychain --keychain login.keychain

Legacy Usage (Backward Compatible)

Single Domain:

keymon --token YOUR_TOKEN --org-id YOUR_ORG_ID --domain example.com

Multiple Sources:

keymon --token YOUR_TOKEN --org-id YOUR_ORG_ID \
  --domain example.com \
  --keystore /path/to/keystore.jks \
  --cert-folder /etc/ssl/certs/ \
  --ca-bundle /etc/ssl/ca-bundle.pem \
  --environment staging \
  --group "Web Services"

Certificate Management

List All Certificates:

keymon --token YOUR_TOKEN --org-id YOUR_ORG_ID --list

Filter by Source:

# List only keystore certificates
keymon --token YOUR_TOKEN --org-id YOUR_ORG_ID --list --source keystore

# List only domain certificates
keymon --token YOUR_TOKEN --org-id YOUR_ORG_ID --list --source domain

# List only Kubernetes certificates
keymon --token YOUR_TOKEN --org-id YOUR_ORG_ID --list --source k8s-secrets

Delete Certificate:

keymon --token YOUR_TOKEN --org-id YOUR_ORG_ID --delete 123

List Available Plugins:

keymon --list-plugins

Using Environment Variables

# Set once
export SSL_GUARDIAN_TOKEN="your_token_here"
export SSL_GUARDIAN_ORG_ID="your_org_id_here"

# Then use without --token and --org-id
keymon --plugin domain --domains example.com
keymon --plugin keystore --keystores /path/to/keystore.jks
keymon --plugin k8s-secrets --namespace prod

# Legacy syntax also works
keymon --domain example.com
keymon --keystore /path/to/keystore.jks

Plugin System

Available Plugins

Plugin	Description	Parameters
`domain`	Live HTTPS domain scanning	`domains` (required)
`keystore`	Java keystores (.jks, .p12, .pfx)	`keystores` (required), `password` (optional)
`cert-folder`	Certificate file directories	`folders` (required)
`pki-bundle`	PKI CA bundles	`bundles` (required)
`k8s-secrets`	Kubernetes TLS secrets	`kubeconfig` (optional), `namespace` (optional)
`nginx`	Nginx configuration files	`config-path` (required)
`aws-acm`	AWS Certificate Manager	`access-key-id`, `secret-access-key` (required), `region` (optional)
`azure-keyvault`	Azure Key Vault	`vault-name`, `client-id`, `client-secret`, `tenant-id` (all required)
`macos-keychain`	macOS Keychain	`keychain` (optional)
`postgres-tls`	PostgreSQL TLS certificates	`data-dir`, `cert-file`, `key-file` (all optional)
`windows-certstore`	Windows Certificate Store	`store` (optional), `location` (optional)

Core Options

Option	Description	Required	Example
`--plugin PLUGIN`	Use specific plugin	Yes*	`--plugin domain`
`--token TOKEN`	SSL Guardian authentication token	Yes**	`--token abc123...`
`--org-id ORG_ID`	Organization ID	Yes**	`--org-id uuid-here`
`--proxy URL`	Proxy URL for HTTP/HTTPS requests	No	`--proxy http://proxy:8080`
`--environment ENV`	Environment tag for certificates	No	`--environment production`
`--group GROUP`	Group tag for certificates	No	`--group "Web Services"`
`--list`	List all certificates with status	No*	`--list`
`--delete ID`	Delete certificate by ID	No*	`--delete 123`
`--list-plugins`	List available plugins	No*	`--list-plugins`

*One of plugin, list, delete, or list-plugins is required
**Required unless set via environment variables

Environment Variables

Variable	Description	Default
`SSL_GUARDIAN_TOKEN`	Authentication token	None
`SSL_GUARDIAN_ORG_ID`	Organization ID	None
`SSL_GUARDIAN_API_URL`	API endpoint	`https://app.sslguardian.io`
`HTTPS_PROXY`	Proxy URL for HTTPS requests	None
`HTTP_PROXY`	Proxy URL for HTTP requests	None
`KEYSTORE_PASSWORD`	Keystore password	`changeit`

Plugin Details

Core Plugins

domain

Purpose: Live HTTPS domain scanning
Protocols: HTTPS/TLS connections
Ports: Default 443, custom ports supported (example.com:8443)
Usage: --plugin domain --domains "example.com,api.example.com"

keystore

Purpose: Java keystores (.jks, .p12, .pfx)
Tool: Native Node.js parsing (no Java required)
Authentication: Password-based (default: changeit)
Usage: --plugin keystore --keystores /path/to/store.jks --password mypass

cert-folder

Purpose: Certificate file directories
Formats: PEM, CRT, CER, CERT, P7B, P7C
Tool: OpenSSL for parsing
Usage: --plugin cert-folder --folders /etc/ssl/certs/

pki-bundle

Purpose: PKI CA bundles
Format: Multi-certificate PEM bundles
Tool: OpenSSL for parsing
Usage: --plugin pki-bundle --bundles /etc/ssl/ca-bundle.pem

Extended Plugins

k8s-secrets

Purpose: Kubernetes TLS secrets
Requirements: Kubeconfig file access
Usage: --plugin k8s-secrets --namespace prod --kubeconfig /path/to/config

nginx

Purpose: Nginx configuration files
Requirements: Access to Nginx config files
Usage: --plugin nginx --config-path /etc/nginx/sites-enabled/

aws-acm

Purpose: AWS Certificate Manager
Requirements: AWS access keys
Usage: --plugin aws-acm --region us-east-1 --access-key-id xxx --secret-access-key xxx

azure-keyvault

Purpose: Azure Key Vault
Requirements: Azure service principal credentials
Usage: --plugin azure-keyvault --vault-name myvault --client-id xxx --client-secret xxx --tenant-id xxx

macos-keychain

Purpose: macOS Keychain
Requirements: macOS system
Usage: --plugin macos-keychain --keychain System.keychain

postgres-tls

Purpose: PostgreSQL TLS certificates
Requirements: Access to PostgreSQL cert files
Usage: --plugin postgres-tls --data-dir /var/lib/postgresql/data

windows-certstore

Purpose: Windows Certificate Store
Requirements: Windows system with PowerShell
Usage: --plugin windows-certstore --store My --location CurrentUser

Output Examples

Certificate Collection

Fetching certificate info for: example.com
✓ Successfully fetched certificate for example.com
Extracting certificate info from keystore: /path/to/keystore.jks
✓ Successfully extracted 3 certificates from /path/to/keystore.jks
Scanning certificate folder: /etc/ssl/certs/
✓ Parsed certificate: internal.example.com
✓ Successfully scanned 1 certificates from /etc/ssl/certs/
Parsing PKI CA bundle: /etc/ssl/ca-bundle.pem
✓ Parsed PKI certificate: Internal Root CA
✓ Parsed PKI certificate: Internal Intermediate CA
✓ Successfully parsed 2 certificates from PKI bundle /etc/ssl/ca-bundle.pem
Submitting 6 certificates to SSL Guardian...
Submission results:
✓ Created: 4
✓ Updated: 2
✗ Errors: 0

Certificate Listing

Found 8 certificates:

ID      Domain                  Status    Days  Source    Issuer
──────────────────────────────────────────────────────────────────────────────────
123     example.com             🟢 valid     45   domain    Let's Encrypt
124     api.example.com         🟡 warning   25   domain    Let's Encrypt  
125     internal.corp.com       🟢 valid     180  keystore  Internal CA
126     Root CA                 🟢 valid     3650 pki       Self-signed
127     old.example.com         🔴 expired   -5   file      DigiCert

Filtered Listing

Found 2 certificates (filtered by source: keystore):

ID      Domain                  Status    Days  Source    Issuer
──────────────────────────────────────────────────────────────────────────────────
125     internal.corp.com       🟢 valid     180  keystore  Internal CA
128     app.internal.com        🟡 warning   15   keystore  Internal CA

Certificate Metadata and Tagging

Automatic Tags

All certificates are automatically tagged with:

source - Origin type (domain, keystore, file, pki)
environment - Environment specified with --environment
group - Group specified with --group

Source-Specific Tags

Domain: Connection details
Keystore: File path, alias information
File: File path, filename
PKI: Bundle path, certificate index

Tag Examples

{
  "source": "pki",
  "environment": "production",
  "group": "Internal Services",
  "bundle_path": "/etc/ssl/ca-bundle.pem",
  "bundle_index": 0
}

Cron Job Scheduling

Install Automated Collection

Every 6 hours with domain plugin:

keymon --plugin domain --domains example.com --cron "0 */6 * * *" --install-cron

Daily at midnight with Kubernetes:

keymon --plugin k8s-secrets --namespace prod \
  --environment production --cron "0 0 * * *" --cron-name "daily-k8s-check" --install-cron

Weekly AWS ACM check:

keymon --plugin aws-acm --region us-east-1 --cron "0 0 * * 0" \
  --cron-name "weekly-acm-check" --install-cron

Legacy syntax (still works):

keymon --domain example.com --keystore /path/to/keystore.jks \
  --environment production --cron "0 0 * * *" --cron-name "daily-ssl-check" --install-cron

Manage Cron Jobs

List all SSL Guardian cron jobs:

keymon --list-cron

Remove specific cron job:

keymon --cron-name "daily-ssl-check" --remove-cron

Common Cron Schedules

Schedule	Description	Example Use Case
`0 /6 * *`	Every 6 hours	High-frequency monitoring
`0 0 * * *`	Daily at midnight	Standard daily checks
`0 0 * * 0`	Weekly on Sunday	Weekly PKI updates
`0 0 1 * *`	Monthly on 1st	Monthly compliance checks
`0 2 * * 1-5`	Weekdays at 2 AM	Business day monitoring

Enterprise Proxy Support

KeyMon supports HTTP/HTTPS proxies for enterprise environments without direct internet access:

Using Environment Variables:

# Set proxy for all requests
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# Run KeyMon normally
keymon --plugin domain --domains example.com

Using Command Line:

# Specify proxy per command
keymon --plugin azure-keyvault --vault-name myvault \
  --proxy http://proxy.company.com:8080 \
  --client-id xxx --client-secret xxx --tenant-id xxx

Proxy Authentication:

# Proxy with authentication
export HTTPS_PROXY=http://username:password@proxy.company.com:8080

# Or via command line
keymon --proxy http://username:password@proxy.company.com:8080 --plugin domain --domains example.com

Supported Proxy Types:

✅ HTTP Proxy - Standard HTTP proxy servers
✅ HTTPS Proxy - Secure proxy connections
✅ Authenticated Proxies - Username/password authentication
✅ Corporate Proxies - Enterprise proxy configurations

Advanced Usage

Plugin-Based Workflows

Multi-Environment Collection:

# Development environment
keymon --plugin domain --domains dev.example.com \
  --environment development --group "Dev Services"

# Production Kubernetes
keymon --plugin k8s-secrets --namespace prod \
  --environment production --group "Production Services"

# AWS Production
keymon --plugin aws-acm --region us-east-1 \
  --environment production --group "AWS Services"

Infrastructure-Specific Collection:

# Web servers (Nginx)
keymon --plugin nginx --config-path /etc/nginx/sites-enabled/ \
  --environment production --group "Web Servers"

# Database servers (PostgreSQL)
keymon --plugin postgres-tls --data-dir /var/lib/postgresql/data \
  --environment production --group "Database Servers"

# Container orchestration (Kubernetes)
keymon --plugin k8s-secrets --namespace default \
  --environment production --group "Container Platform"

Certificate Management Workflow:

# 1. List available plugins
keymon --list-plugins

# 2. Collect certificates from specific source
keymon --plugin k8s-secrets --namespace prod

# 3. List and review
keymon --list

# 4. Filter by plugin source
keymon --list --source k8s-secrets

# 5. Remove unwanted certificates
keymon --delete 123

Legacy Batch Processing (still works):

keymon --token TOKEN --org-id ORG_ID \
  --domain api.example.com \
  --keystore /opt/app/keystore.jks \
  --cert-folder /etc/ssl/certs/ \
  --ca-bundle /etc/ssl/internal-ca.pem \
  --environment production \
  --group "Production Services"

API Integration

KeyMon integrates with SSL Guardian's REST API. All plugins submit certificates using the same API endpoints:

Submit Certificates

curl -X POST "https://app.sslguardian.io/v1/collector/submit" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -H "org-id: YOUR_ORG_ID" \
  -d '{
    "certificates": [
      {
        "domain": "example.com",
        "issuer": "Let'\''s Encrypt",
        "expiration_date": "2024-12-31T23:59:59Z",
        "tags": { 
          "source": "domain",
          "environment": "production",
          "group": "Web Services"
        }
      }
    ]
  }'

List Certificates

curl -X GET "https://app.sslguardian.io/v1/collector/certificates" \
  -H "token: YOUR_TOKEN" \
  -H "org-id: YOUR_ORG_ID"

Delete Certificate

curl -X DELETE "https://app.sslguardian.io/v1/collector/certificates/CERT_ID" \
  -H "token: YOUR_TOKEN" \
  -H "org-id: YOUR_ORG_ID"

Creating Custom Plugins

KeyMon's plugin system makes it easy to add support for new certificate sources:

const BasePlugin = require('../lib/base-plugin');

class MyPlugin extends BasePlugin {
  constructor() {
    super();
    this.name = 'my-plugin';
    this.description = 'My custom certificate source';
    this.requiredParams = ['param1'];
  }

  async collect(config) {
    this.validateConfig(config);
    
    // Your collection logic here
    const certificates = [];
    
    // Use this.createCertificate() to create certificate objects
    certificates.push(this.createCertificate({
      domain: 'example.com',
      issuer: 'My CA',
      expiration_date: new Date(),
      valid_from: new Date(),
      environment: config.environment,
      group: config.group,
      tags: { custom_tag: 'value' }
    }));
    
    return certificates;
  }
}

module.exports = MyPlugin;

Save as plugins/my-plugin.js and use with:

keymon --plugin my-plugin --param1 value

Troubleshooting

Plugin-Specific Issues

Plugin not found:

# List available plugins
keymon --list-plugins

# Check plugin file exists (from source)
ls plugins/

Plugin parameter errors:

# Check plugin help
keymon --help

# Verify required parameters are provided
keymon --plugin domain --domains example.com

Common Issues by Plugin

keystore plugin:

No Java installation required (uses native Node.js parsing)
Set KEYSTORE_PASSWORD environment variable if needed
Supports .jks, .p12, and .pfx formats

k8s-secrets plugin:

Ensure kubeconfig file is accessible
Verify cluster connectivity and secret read permissions
No kubectl installation required

aws-acm plugin:

Create AWS IAM user with ACM read permissions
Use access-key-id and secret-access-key parameters
Verify ACM permissions in target region

azure-keyvault plugin:

Create Azure service principal with Key Vault access
Ensure service principal has 'Certificate User' role on Key Vault
Verify client-id, client-secret, and tenant-id are correct

nginx plugin:

Ensure access to Nginx configuration files
Verify certificate file paths in configs

cert-folder/pki-bundle plugins:

Install OpenSSL: brew install openssl (macOS) or apt-get install openssl (Ubuntu)
Verify file paths and permissions

General issues:

"Invalid token": Verify token and org-id are correct
"Connection timeout": Check network connectivity and firewall settings
"No certificates found": Verify source accessibility and parameters

Debug Mode

Add verbose logging by modifying the script or contact support for assistance.

Security Notes

Secure Transmission - All data transmitted over HTTPS with token authentication
Local Processing - Certificates processed locally before upload
No Private Keys - Only public certificate data is extracted and transmitted
Metadata Only - Certificate metadata, fingerprints, and expiration data uploaded
Token Security - Use secure token storage and rotation practices
File Permissions - Ensure certificate files have appropriate access controls
Temporary Files - Temporary files are automatically cleaned up after processing

CLI Reference

Exit Codes

0 - Success
1 - General error (missing arguments, file not found, etc.)
2 - Authentication error
3 - Network/API error

Status Indicators

🟢 valid - More than 30 days remaining
🟡 warning - 8-30 days remaining
🟠 critical - 1-7 days remaining
🔴 expired - Past expiration date

Source Types

domain - Live domain certificate
keystore - Java keystore certificate
file - Certificate file
pki - PKI CA bundle certificate

Changelog

See CHANGELOG.md for detailed release notes and version history.

Support

Documentation: SSL Guardian Docs
Support: support@sslguardian.io
Issues: Report via SSL Guardian dashboard

Contributing

We welcome contributions! To add a new plugin:

Create a new plugin file in plugins/
Extend the BasePlugin class
Implement the collect() method
Test your plugin
Submit a pull request

See PLUGINS.md for detailed plugin development guide.

License

Keywords

FAQs

What is keymon?

Is keymon popular?

Is keymon well maintained?

Package last updated on 02 Aug 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

keymon

KeyMon - SSL Guardian Collector

🔌 Plugin Architecture

Core Plugins

Extended Plugins

Features

Prerequisites

Required

Optional

Installation

NPM Package (Recommended)

From Source

Authentication Setup

Usage

Plugin-Based Usage (Recommended)

Legacy Usage (Backward Compatible)

Certificate Management

Using Environment Variables

Plugin System

Available Plugins

Core Options

Environment Variables

Plugin Details

Core Plugins

domain

keystore

cert-folder

pki-bundle

Extended Plugins

k8s-secrets

nginx

aws-acm

azure-keyvault

macos-keychain

postgres-tls

windows-certstore

Output Examples

Certificate Collection

Certificate Listing

Filtered Listing

Certificate Metadata and Tagging

Automatic Tags

Source-Specific Tags

Tag Examples

Cron Job Scheduling

Install Automated Collection

Manage Cron Jobs

Common Cron Schedules

Enterprise Proxy Support

Using Environment Variables:

Using Command Line:

Proxy Authentication:

Supported Proxy Types:

Advanced Usage

Plugin-Based Workflows

API Integration

Submit Certificates

List Certificates

Delete Certificate

Creating Custom Plugins

Troubleshooting

Plugin-Specific Issues

Common Issues by Plugin

Debug Mode

Security Notes

CLI Reference

Exit Codes

Status Indicators

Source Types

Changelog

Support

Contributing

License

Keywords

Related posts

Axios Maintainer Confirms Social Engineering Attack Behind npm Compromise

Node.js Drops Bug Bounty Rewards After Funding Dries Up