Secure Configuration Guide - TYCHON Quantum Readiness

Overview & Features

What is Secure Configuration?

The Secure Configuration feature allows you to store sensitive credentials (Elasticsearch, Kafka, S3, Splunk) in an encrypted configuration file instead of passing them as command-line arguments or environment variables each time you run a scan.

Key Benefit: Set up your credentials once, and certscanner automatically loads them for every scan - no plaintext passwords in commands, scripts, or logs.

Supported Integrations

📊

Elasticsearch

Node URL and API Key authentication

🔄

Apache Kafka

Comprehensive SSL/TLS + SASL configuration

☁️

AWS S3 Storage

Access keys and S3-compatible endpoints

📡

Splunk HEC

Token and basic auth with index selection

Key Features

🔐 FIPS 140-3 Compliant

Military-grade encryption with industry-standard key derivation meeting federal compliance requirements

🔑 Flexible Authentication

Environment variables, automatic encryption, or built-in password fallback

💾 Centralized Storage

Single encrypted config.enc file per user with 0600 permissions

🛡️ Security Hardening

Built-in protections prevent credential extraction from binary

⚡ Easy Integration

One-time setup, automatic credential loading for every scan

🔄 Multi-Platform

Windows, macOS, Linux with platform-specific secure storage locations

Getting Started

✅ Quick Start Guide

Follow these platform-specific steps to configure secure credential storage in under 5 minutes.

Windows Quick Start

1️⃣

Configure Your Credentials

Run certscanner with the -config flag and your credentials:

certscanner.exe -config `
  -config-elasticnode "https://elastic.company.com:9200" `
  -config-elasticapikey "your-elastic-api-key"

Config will be saved to: .\config.enc (same directory as certscanner.exe)

2️⃣

Verify Storage Location

Check that the encrypted config file was created:

dir .\config.enc

3️⃣

Run Scans with Stored Credentials

Now run scans without specifying credentials - they load automatically:

# Credentials automatically loaded from secure config
certscanner.exe -host 192.168.1.0/24 -posttoelastic

4️⃣

(Optional) Set Custom Password

For added security, use a custom encryption password:

$env:TYCHON_CONFIG_KEY="MySecurePassword123!"
certscanner.exe -host 192.168.1.0/24 -posttoelastic

Linux Quick Start

1️⃣

Configure Your Credentials

Run certscanner with the -config flag and your credentials:

./certscanner -config \
  -config-elasticnode "https://elastic.company.com:9200" \
  -config-elasticapikey "your-elastic-api-key"

Config will be saved to: ./config.enc (same directory as certscanner)

2️⃣

Verify Storage Location

Check that the encrypted config file was created:

ls -la ./config.enc
# Should show: -rw------- (permissions 0600)

3️⃣

Run Scans with Stored Credentials

Now run scans without specifying credentials - they load automatically:

# Credentials automatically loaded from secure config
./certscanner -host 192.168.1.0/24 -posttoelastic

4️⃣

(Optional) Set Custom Password

For added security, use a custom encryption password:

export TYCHON_CONFIG_KEY="MySecurePassword123!"
./certscanner -host 192.168.1.0/24 -posttoelastic

macOS Quick Start

1️⃣

Configure Your Credentials

Run certscanner with the -config flag and your credentials:

./certscanner -config \
  -config-elasticnode "https://elastic.company.com:9200" \
  -config-elasticapikey "your-elastic-api-key"

Config will be saved to: ./config.enc (same directory as certscanner)

2️⃣

Verify Storage Location

Check that the encrypted config file was created:

ls -la ./config.enc
# Should show: -rw------- (permissions 0600)

3️⃣

Run Scans with Stored Credentials

Now run scans without specifying credentials - they load automatically:

# Credentials automatically loaded from secure config
./certscanner -host 192.168.1.0/24 -posttoelastic

4️⃣

(Optional) Set Custom Password

For added security, use a custom encryption password:

export TYCHON_CONFIG_KEY="MySecurePassword123!"
./certscanner -host 192.168.1.0/24 -posttoelastic

Configuration Setup

Configure credentials for different integrations using the -config flag combined with integration-specific flags. You can configure multiple integrations at once.

📊 Elasticsearch

🔄 Kafka

☁️ S3 Storage

📡 Splunk

Elasticsearch Configuration

Available Flags

Flag	Description	Example
-config-elasticnode	Elasticsearch node URL	https://elastic.company.com:9200
-config-elasticapikey	Elasticsearch API Key	your-api-key-here

Example Setup

./certscanner -config \
  -config-elasticnode "https://elastic.company.com:9200" \
  -config-elasticapikey "your-elastic-api-key"

💡 Tip: After configuration, use -posttoelastic flag during scans to automatically post results to your configured Elasticsearch cluster.

Apache Kafka Configuration

⚠️ Note: Kafka configuration supports comprehensive SSL/TLS and SASL authentication options. Configure only the options your Kafka cluster requires.

Basic Configuration Flags

Flag	Description	Example
-config-kafkabrokers	Kafka broker addresses	kafka1:9092,kafka2:9092
-config-kafkausername	SASL username	scanner-user
-config-kafkapassword	SASL password	secure-password
-config-kafkasecurityprotocol	Security protocol	SASL_SSL
-config-kafkasaslmechanism	SASL mechanism	SCRAM-SHA-256

SSL/TLS Configuration Flags

Flag	Description
-config-kafkasslcalocation	Path to CA certificate
-config-kafkasslcertlocation	Path to client certificate
-config-kafkasslkeylocation	Path to client private key
-config-kafkasslkeypassword	Private key passphrase
-config-kafkasslkeystorelocation	Path to JKS keystore
-config-kafkasslkeystorepassword	Keystore password
-config-kafkassltruststorelocation	Path to JKS truststore
-config-kafkassltruststorepassword	Truststore password
-config-kafkasslenabledprotocols	Enabled SSL protocols (comma-separated)
-config-kafkasslendpointidentificationalgorithm	Hostname verification algorithm

Example: SASL/SSL Configuration

./certscanner -config \
  -config-kafkabrokers "kafka1.company.com:9093,kafka2.company.com:9093" \
  -config-kafkausername "certscanner" \
  -config-kafkapassword "secure-password" \
  -config-kafkasecurityprotocol "SASL_SSL" \
  -config-kafkasaslmechanism "SCRAM-SHA-256" \
  -config-kafkasslcalocation "/etc/ssl/certs/ca-bundle.crt"

S3 Storage Configuration

Available Flags

Flag	Description	Example
-config-s3region	AWS region	us-east-1
-config-s3accesskey	AWS Access Key ID	AKIAIOSFODNN7EXAMPLE
-config-s3secretkey	AWS Secret Access Key	wJalrXUtnFEMI/K7MDENG...
-config-s3endpoint	Custom S3 endpoint (for S3-compatible storage)	https://s3.company.com

Example: AWS S3 Configuration

./certscanner -config \
  -config-s3region "us-east-1" \
  -config-s3accesskey "AKIAIOSFODNN7EXAMPLE" \
  -config-s3secretkey "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Example: S3-Compatible Storage (MinIO, Cloudflare R2)

./certscanner -config \
  -config-s3endpoint "https://s3.company.com" \
  -config-s3region "us-east-1" \
  -config-s3accesskey "minioadmin" \
  -config-s3secretkey "minioadmin"

💡 Tip: After configuration, use -upload-s3 flag with your bucket name to upload scan results: -upload-s3 my-bucket-name

Splunk HEC Configuration

Available Flags

Flag	Description	Example
-config-splunkurl	Splunk HEC URL	https://splunk.company.com:8088
-config-splunktoken	HEC token (preferred)	your-hec-token-here
-config-splunkusername	Basic auth username (alternative)	admin
-config-splunkpassword	Basic auth password (alternative)	secure-password
-config-splunkindex	Target Splunk index	pqc_scans

Example: HEC Token Configuration

./certscanner -config \
  -config-splunkurl "https://splunk.company.com:8088" \
  -config-splunktoken "your-hec-token-here" \
  -config-splunkindex "pqc_scans"

Example: Basic Auth Configuration

./certscanner -config \
  -config-splunkurl "https://splunk.company.com:8088" \
  -config-splunkusername "admin" \
  -config-splunkpassword "secure-password" \
  -config-splunkindex "pqc_scans"

💡 Tip: After configuration, use -posttosplunk flag during scans to automatically send results to Splunk HEC.

Usage Examples

Single Integration (Elasticsearch Only)

Before: Insecure (credentials in command line)

# ❌ Credentials visible in command line, logs, process list
./certscanner -host 192.168.1.0/24 \
  -elasticnode "https://elastic.company.com:9200" \
  -elasticapikey "your-api-key-exposed-in-logs"

After: Secure (credentials encrypted)

# ✅ Set up once
./certscanner -config \
  -config-elasticnode "https://elastic.company.com:9200" \
  -config-elasticapikey "your-api-key"

# ✅ Run scans securely - credentials loaded automatically
./certscanner -host 192.168.1.0/24 -posttoelastic

Multiple Integrations (Elasticsearch + S3)

# Configure both integrations at once
./certscanner -config \
  -config-elasticnode "https://elastic.company.com:9200" \
  -config-elasticapikey "your-elastic-api-key" \
  -config-s3region "us-east-1" \
  -config-s3accesskey "AKIAIOSFODNN7EXAMPLE" \
  -config-s3secretkey "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

# Use both integrations in a scan
./certscanner -host 10.0.0.0/8 \
  -posttoelastic \
  -upload-s3 my-scan-results-bucket

Full Enterprise Setup (All Integrations)

./certscanner -config \
  -config-elasticnode "https://elastic.company.com:9200" \
  -config-elasticapikey "elastic-key" \
  -config-kafkabrokers "kafka1:9093,kafka2:9093" \
  -config-kafkausername "certscanner" \
  -config-kafkapassword "kafka-password" \
  -config-kafkasecurityprotocol "SASL_SSL" \
  -config-kafkasaslmechanism "SCRAM-SHA-256" \
  -config-s3region "us-east-1" \
  -config-s3accesskey "AKIAIOSFODNN7EXAMPLE" \
  -config-s3secretkey "secret-key" \
  -config-splunkurl "https://splunk.company.com:8088" \
  -config-splunktoken "splunk-hec-token" \
  -config-splunkindex "pqc_scans"

Environment Variable Override (Production Recommended)

# Set custom encryption password (recommended for production)
export TYCHON_CONFIG_KEY="MyProductionPassword2025!"

# Configure credentials (encrypted with custom password)
./certscanner -config \
  -config-elasticnode "https://elastic.company.com:9200" \
  -config-elasticapikey "your-api-key"

# All subsequent scans must use the same TYCHON_CONFIG_KEY
export TYCHON_CONFIG_KEY="MyProductionPassword2025!"
./certscanner -host 192.168.1.0/24 -posttoelastic

CI/CD Pipeline Integration

# GitHub Actions / GitLab CI / Jenkins example
steps:
  - name: Configure Certscanner Credentials
    run: |
      export TYCHON_CONFIG_KEY="${{ secrets.TYCHON_CONFIG_KEY }}"
      ./certscanner -config \
        -config-elasticnode "${{ secrets.ELASTIC_NODE }}" \
        -config-elasticapikey "${{ secrets.ELASTIC_API_KEY }}"

  - name: Run Security Scan
    run: |
      export TYCHON_CONFIG_KEY="${{ secrets.TYCHON_CONFIG_KEY }}"
      ./certscanner -host $TARGET_NETWORK -posttoelastic

Security Architecture

🔒 FIPS 140-3 Compliant Encryption

All credentials are protected using military-grade encryption standards approved for federal government use. The secure configuration system uses industry-standard cryptographic algorithms to ensure your sensitive credentials remain protected both at rest and in transit.

What This Protects: Elasticsearch, Kafka, S3, and Splunk credentials stored on disk are encrypted and cannot be read without proper authorization.

🎯 Threat Model

This secure configuration feature is designed to protect against:

Credential Theft from Disk: Encrypted storage prevents reading credentials from config files
Network Transmission: Credentials loaded from encrypted storage, not command-line arguments
Process Monitoring: No plaintext credentials visible in command-line arguments or process lists
Accidental Exposure: Config files won't leak credentials if accidentally shared or backed up
Unauthorized Access: Strict file permissions limit access to the config.enc file

Important: This system protects credentials at rest and in transit. It does not protect against attackers who have SYSTEM (Windows) or root (Linux/macOS) access to the machine where certscanner runs. For such scenarios, use secrets management systems and implement proper system hardening.

🔐 Encryption

Credentials are encrypted using FIPS 140-3 approved cryptographic algorithms with authenticated encryption to detect tampering attempts.

✓ Benefits: Military-grade protection, tamper detection, compliance-ready

🔑 Key Derivation

Master passwords are processed through industry-standard key derivation functions that resist brute-force attacks and meet current NIST recommendations.

✓ Benefits: Brute-force resistance, NIST compliant, password hardening

🛡️ File Protection

The config.enc file is automatically protected with strict file system permissions (0600) and directory permissions (0700) to prevent unauthorized access.

✓ Benefits: OS-level protection, owner-only access, automatic hardening

Configuration File Storage

The encrypted configuration is stored in a file named config.enc located in the same directory as the certscanner binary. This design simplifies enterprise deployment and cleanup.

⚠️ Security Note: File permissions are automatically set to 0600 (owner read/write only). The directory is created with 0700 permissions. Never modify these permissions or the encrypted file may become accessible to unauthorized users.

💡 Enterprise Benefit: Binary-relative storage makes cleanup easy for deployment platforms like BigFix, SCCM, and Intune—simply delete the certscanner directory to remove everything.

Master Password Management

The secure configuration system uses a 3-tier priority system for determining the master password used to encrypt/decrypt credentials. Higher priority methods override lower priority methods.

🎯 Deployment Context Matters

For System Services (BigFix/SCCM/Intune): Automatic Encryption (Priority 1) is recommended—zero configuration, machine-locked.
For Secrets Managers (Vault/CyberArk): TYCHON_CONFIG_KEY (Priority 2) allows centralized credential management.
Threat Model: Protects credentials at rest and in transit. Does not protect against attackers with SYSTEM/root access.

1️⃣

Automatic Encryption (Default)

✅ RECOMMENDED FOR SYSTEM SERVICES

The default encryption method. Works automatically with zero configuration required. Perfect for deployments via BigFix, SCCM, Intune, Ansible—no passwords to manage.

✅ Benefits

Zero Configuration: Works automatically, no setup required
Machine-Locked: Configuration stays with the deployment machine
No Password Management: No credentials to distribute or rotate
Isolated Deployments: Each machine has independent encryption
System Service Compatible: Works with SYSTEM/root accounts
Compliance-Ready: Per-machine encryption for audit requirements

⚠️ Limitations

Not Portable: Configuration files don't transfer between machines
Reinstall Requirement: Reconfiguration needed if binary moves
User-Specific: Different user accounts require separate configs
Decentralized: No central password management

✅ Perfect For:

Enterprise deployments via BigFix, SCCM, Intune, Ansible
System service accounts (NT AUTHORITY\SYSTEM, root)
Air-gapped or isolated environments
Scenarios requiring per-machine encryption isolation

2️⃣

TYCHON_CONFIG_KEY Environment Variable

🔑 RECOMMENDED FOR SECRETS MANAGERS

Use the TYCHON_CONFIG_KEY environment variable when integrating with enterprise secrets management systems like HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or CyberArk.

Setting the Environment Variable

Linux/macOS (bash/zsh):

export TYCHON_CONFIG_KEY="your-secure-password-here"
./certscanner -config

Windows PowerShell:

$env:TYCHON_CONFIG_KEY="your-secure-password-here"
.\certscanner.exe -config

Windows Command Prompt:

set TYCHON_CONFIG_KEY=your-secure-password-here
certscanner.exe -config

Secrets Manager Integration

HashiCorp Vault Example:

export TYCHON_CONFIG_KEY=$(vault kv get -field=password secret/certscanner/config)
./certscanner -posttoelastic

AWS Secrets Manager Example:

export TYCHON_CONFIG_KEY=$(aws secretsmanager get-secret-value \
  --secret-id certscanner/config --query SecretString --output text)
./certscanner -posttoelastic

Kubernetes Secret Example:

env:
  - name: TYCHON_CONFIG_KEY
    valueFrom:
      secretKeyRef:
        name: certscanner-config
        key: encryption-password

✅ Benefits

Centralized Management: Store passwords in secrets managers
Customer Isolation: Different passwords per customer/environment
Password Rotation: Update passwords without rebuilding
Audit Trail: Track credential access in secrets manager
Portable Config: Move config files between machines

⚠️ Important Notes

Persistence: Environment variable must be set each time
Process Visibility: May be visible to other processes on the system
Secrets Manager Best: Always use secrets managers in production
Strong Passwords: Use long, randomly generated passwords

✅ Perfect For:

Integrations with HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, CyberArk
Multi-tenant environments where each customer needs isolated credentials
Compliance requirements for centralized credential management
Scenarios requiring regular password rotation without redeployment

3️⃣

Built-In Password

🔐 AUTOMATIC FALLBACK

If neither TYCHON_CONFIG_KEY nor automatic encryption is available, the system uses a built-in password that provides automatic encryption/decryption capabilities without additional configuration.

Security Considerations

Automatic Operation: Works out-of-the-box without configuration
Hardened Protection: Built-in security mechanisms prevent simple extraction
Best Practice: Use automatic encryption or TYCHON_CONFIG_KEY for production deployments
Portability: Config files can be copied between systems using this method

When to Use

This fallback method is suitable for:

Development and testing environments
Quick deployment scenarios
Environments where config portability is needed

⚠️ Production Recommendation: Always use TYCHON_CONFIG_KEY for production deployments to ensure customer-specific password isolation and enhanced security.

Priority Order Flowchart

🔍

Use Automatic Encryption → Default method, machine-locked (Priority 1)

⬇️

If TYCHON_CONFIG_KEY is set...

🔍

Use Environment Variable → TYCHON_CONFIG_KEY password (Priority 2)

⬇️

If not available...

🔍

Use Built-In Password → Automatic fallback (Priority 3)

Platform-Specific Details

Windows Platform Details

📁 File Location

The config.enc file is stored in the same directory as certscanner.exe

Example: If certscanner.exe is located at: C:\Tools\CertScanner\certscanner.exe

Then config.enc will be stored at:

C:\Tools\CertScanner\config.enc

✅ Enterprise Benefit: This design makes cleanup easy for deployment platforms like BigFix, SCCM, and Intune—simply delete the certscanner folder to remove everything.

🔐 File Permissions

Directory Permissions: The certscanner directory should have appropriate NTFS permissions to prevent unauthorized access.

File Permissions: config.enc is automatically created with restricted permissions (owner read/write only).

Verify Permissions (PowerShell):

Get-Acl .\config.enc | Format-List

⚙️ Environment Variable Setup

PowerShell (Session-only):

$env:TYCHON_CONFIG_KEY="MySecurePassword123!"

PowerShell (Persistent - User):

[Environment]::SetEnvironmentVariable("TYCHON_CONFIG_KEY", "MySecurePassword123!", "User")

Command Prompt (Session-only):

set TYCHON_CONFIG_KEY=MySecurePassword123!

Linux Platform Details

📁 File Location

The config.enc file is stored in the same directory as the certscanner binary

Example: If certscanner is located at: /opt/certscanner/certscanner

Then config.enc will be stored at:

/opt/certscanner/config.enc

✅ Enterprise Benefit: This design makes cleanup easy for deployment platforms like Ansible, Puppet, and BigFix—simply remove the certscanner directory to clean up everything.

🔐 File Permissions

File Permissions: 0600 (-rw-------)

Verify Permissions:

ls -la ./config.enc
# Should show: -rw------- (permissions 0600)

⚠️ Security: Only the file owner can read/write. All other users are denied access. Never use chmod to weaken these permissions.

⚙️ Environment Variable Setup

Bash (Session-only):

export TYCHON_CONFIG_KEY="MySecurePassword123!"

Bash (Persistent - add to ~/.bashrc or ~/.profile):

echo 'export TYCHON_CONFIG_KEY="MySecurePassword123!"' >> ~/.bashrc
source ~/.bashrc

Systemd Service (recommended for daemons):

[Service]
Environment="TYCHON_CONFIG_KEY=MySecurePassword123!"
# Or load from file:
EnvironmentFile=/etc/certscanner/config.env

macOS Platform Details

📁 File Location

The config.enc file is stored in the same directory as the certscanner binary

Example: If certscanner is located at: /Applications/CertScanner/certscanner

Then config.enc will be stored at:

/Applications/CertScanner/config.enc

✅ Enterprise Benefit: This design makes cleanup easy for deployment platforms like Workspace ONE and Intune—simply remove the certscanner directory to clean up everything.

🔐 File Permissions

File Permissions: 0600 (-rw-------)

Verify Permissions:

ls -la ./config.enc
# Should show: -rw------- (permissions 0600)

⚙️ Environment Variable Setup

Zsh (Session-only):

export TYCHON_CONFIG_KEY="MySecurePassword123!"

Zsh (Persistent - add to ~/.zshrc):

echo 'export TYCHON_CONFIG_KEY="MySecurePassword123!"' >> ~/.zshrc
source ~/.zshrc

Bash (Session-only):

export TYCHON_CONFIG_KEY="MySecurePassword123!"

💡 Tip: macOS Catalina (10.15) and later use Zsh as the default shell. Earlier versions use Bash.

Best Practices

✅ Security Checklist

Follow these best practices to maximize the security of your credential storage.

🔐 Password Management

✅ Use TYCHON_CONFIG_KEY in production - Always use environment variable passwords in production deployments
✅ Rotate credentials regularly - Update passwords quarterly or after security incidents
✅ Use strong passwords - Minimum 16 characters, mix of letters/numbers/symbols
✅ Different passwords per environment - Separate credentials for dev/staging/production
✅ Document password locations - Maintain secure documentation of which secrets manager stores passwords

🛡️ Access Control

✅ Restrict file system access - Limit OS user access to config directories
✅ Use secrets management systems - HashiCorp Vault, AWS Secrets Manager, Azure Key Vault
✅ Audit credential access logs - Monitor who accesses credential files and when
✅ Back up configs securely - Encrypted backups stored separately from production
✅ Monitor failed authentication - Alert on repeated decryption failures

🧪 Testing & Validation

✅ Test credential loading - Verify config works before production deployment
✅ Validate file permissions - Confirm 0600 permissions on config files
✅ Test environment variable override - Ensure TYCHON_CONFIG_KEY takes precedence
✅ Verify encrypted storage - Check that config.enc is properly encrypted
✅ Run security scans - Use static analysis tools on deployment scripts

📋 Operational Excellence

✅ Use per-customer credentials - Separate credentials for each customer deployment
✅ Implement credential rotation - Automate password changes on schedule
✅ Log configuration changes - Track when credentials are updated
✅ Document recovery procedures - Have plan for lost passwords or corrupted configs
✅ Review access regularly - Quarterly audits of who has config access

Deployment Patterns

Standalone Deployments

For single-machine deployments, automatic encryption (Priority 1) provides good security without additional configuration.

Recommended: Set TYCHON_CONFIG_KEY once during installation for added security.

Containerized Deployments (Docker/Kubernetes)

Use Kubernetes secrets or Docker secrets to inject TYCHON_CONFIG_KEY. Configure credentials once, reuse across container restarts.

# Kubernetes example
env:
  - name: TYCHON_CONFIG_KEY
    valueFrom:
      secretKeyRef:
        name: certscanner-credentials
        key: config-password

Enterprise Automation (Ansible, BigFix, SCCM)

Use automation tools to configure credentials across fleet. Store TYCHON_CONFIG_KEY in encrypted Ansible Vault or similar.

# Ansible example
- name: Configure CertScanner credentials
  environment:
    TYCHON_CONFIG_KEY: "{{ vault_certscanner_password }}"
  shell: |
    ./certscanner -config \
      -config-elasticnode "{{ elastic_url }}" \
      -config-elasticapikey "{{ vault_elastic_key }}"

CI/CD Pipelines

Store TYCHON_CONFIG_KEY and integration credentials in CI/CD secrets. Configure once per pipeline execution.

# GitHub Actions example
jobs:
  scan:
    steps:
      - name: Configure credentials
        env:
          TYCHON_CONFIG_KEY: ${{ secrets.TYCHON_CONFIG_KEY }}
          ELASTIC_NODE: ${{ secrets.ELASTIC_NODE }}
          ELASTIC_KEY: ${{ secrets.ELASTIC_KEY }}
        run: |
          ./certscanner -config \
            -config-elasticnode "$ELASTIC_NODE" \
            -config-elasticapikey "$ELASTIC_KEY"

Troubleshooting

🔧 Common Issues and Solutions

Use this section to diagnose and resolve common secure configuration problems.

Issue	Symptom	Solution
Credentials not loading	"Failed to load secure config" error	1. Verify config.enc file exists 2. Check TYCHON_CONFIG_KEY matches 3. Re-run -config setup
Permission denied	Cannot read/write config.enc	1. Check file permissions (should be 0600) 2. Verify file ownership 3. Run as correct user
Decryption failure	"Failed to decrypt config" error	1. Verify TYCHON_CONFIG_KEY is correct 2. Check if config was created with different password 3. Re-create config with correct password
Config file not found	No config.enc in expected location	1. Run initial -config setup 2. Check same directory as certscanner binary 3. Verify write permissions in binary directory
Empty TYCHON_CONFIG_KEY	Config created but decryption fails	1. Check environment variable is set 2. Use same TYCHON_CONFIG_KEY for both setup and usage 3. Use automatic encryption (default method)
Config corrupted	Invalid JSON or decryption errors	1. Delete config.enc 2. Re-run -config setup 3. Restore from backup if available
Migration issues	Config doesn't work after machine change	1. Automatic encryption is machine-specific 2. Use TYCHON_CONFIG_KEY for portability 3. Re-configure on new machine

Debug Commands

Verify Config File Location

# Check if config file exists (in same directory as certscanner.exe)
Test-Path .\config.enc

# View file details
Get-Item .\config.enc | Format-List

# Check permissions
Get-Acl .\config.enc | Format-List

# Check if config file exists (in same directory as certscanner binary)
ls -la ./config.enc

# View file details with permissions
stat ./config.enc

# Check directory permissions
ls -lad .

# Check if config file exists (in same directory as certscanner binary)
ls -la ./config.enc

# View file details with permissions
stat ./config.enc

# Check directory permissions
ls -lad .

Test Environment Variable

# PowerShell: Check if TYCHON_CONFIG_KEY is set
$env:TYCHON_CONFIG_KEY

# If empty, it's not set
# If shows value, it's correctly set

# Bash/Zsh: Check if TYCHON_CONFIG_KEY is set
echo $TYCHON_CONFIG_KEY

# If empty, it's not set
# If shows value, it's correctly set

# Check all environment variables
env | grep TYCHON

Validate Config JSON Structure

# Linux/macOS: View config file contents
cat ./config.enc | jq .

# Windows PowerShell: View config file contents
Get-Content .\config.enc | ConvertFrom-Json

# Expected fields:
# - version: (string)
# - algorithm: (encryption algorithm identifier)
# - key_derivation: (key derivation function identifier)
# - salt: (base64-encoded cryptographic salt)
# - nonce: (base64-encoded nonce)
# - encrypted_data: (base64-encoded encrypted credentials)

Common Error Messages

Error: Failed to load secure config: no such file or directory

Cause: Config file doesn't exist

Fix: Run certscanner -config with your credentials

Error: Failed to decrypt secure config: cipher: message authentication failed

Cause: Wrong password or corrupted config

Fix: Check TYCHON_CONFIG_KEY matches, or re-create config

Info: Using automatic encryption (no TYCHON_CONFIG_KEY set)

Cause: Environment variable not set, falling back to Priority 2

Fix: This is OK, but set TYCHON_CONFIG_KEY for production

Info: Secure config loaded successfully

Meaning: Credentials decrypted and loaded correctly

Action: None - system working as expected

Technical Reference

Complete Flag Reference

Flag	Type	Description	Integration
-config-elasticnode	string	Elasticsearch node URL	Elasticsearch
-config-elasticapikey	string	Elasticsearch API Key	Elasticsearch
-config-kafkabrokers	string	Kafka broker addresses (comma-separated)	Kafka
-config-kafkausername	string	Kafka SASL username	Kafka
-config-kafkapassword	string	Kafka SASL password	Kafka
-config-kafkasecurityprotocol	string	Security protocol (PLAINTEXT, SSL, SASL_SSL, etc.)	Kafka
-config-kafkasaslmechanism	string	SASL mechanism (PLAIN, SCRAM-SHA-256, SCRAM-SHA-512)	Kafka
-config-kafkasslcalocation	string	CA certificate file path	Kafka
-config-kafkasslcertlocation	string	Client certificate file path	Kafka
-config-kafkasslkeylocation	string	Client private key file path	Kafka
-config-kafkasslkeypassword	string	Private key passphrase	Kafka
-config-kafkasslkeystorelocation	string	JKS keystore file path	Kafka
-config-kafkasslkeystorepassword	string	Keystore password	Kafka
-config-kafkassltruststorelocation	string	JKS truststore file path	Kafka
-config-kafkassltruststorepassword	string	Truststore password	Kafka
-config-kafkasslenabledprotocols	string	Enabled SSL protocols (comma-separated)	Kafka
-config-kafkasslendpointidentificationalgorithm	string	Hostname verification algorithm	Kafka
-config-s3region	string	AWS region	S3
-config-s3accesskey	string	AWS Access Key ID	S3
-config-s3secretkey	string	AWS Secret Access Key	S3
-config-s3endpoint	string	Custom S3 endpoint (for S3-compatible storage)	S3
-config-splunkurl	string	Splunk HEC URL	Splunk
-config-splunktoken	string	Splunk HEC token	Splunk
-config-splunkusername	string	Splunk basic auth username	Splunk
-config-splunkpassword	string	Splunk basic auth password	Splunk
-config-splunkindex	string	Target Splunk index	Splunk

Security Compliance

The secure configuration system meets industry security standards and compliance requirements:

✓ FIPS 140-3 Compliant

Uses encryption algorithms approved by NIST for federal government use, meeting strict cryptographic standards for sensitive data protection.

✓ Industry Standard

Implements current NIST recommendations for key derivation and encryption, providing military-grade protection for stored credentials.

✓ Authenticated Encryption

Uses authenticated encryption with associated data (AEAD) to detect tampering attempts and ensure data integrity.

✓ Brute-Force Resistant

Key derivation functions are tuned to meet current NIST guidelines, making password cracking computationally infeasible.

Integration Notes

The secure configuration system provides a simple programmatic interface for integration into automated workflows:

Configuration Storage

Credentials are automatically encrypted and stored in config.enc in the same directory as the certscanner binary. The system handles all encryption/decryption operations transparently.

Credential Loading

When certscanner runs with integration flags (-posttoelastic, -posttokafka, etc.), credentials are automatically loaded from encrypted storage. No additional code changes are required.

Master Password Priority

The system uses a 3-tier priority to determine the encryption method: (1) Automatic encryption (default), (2) TYCHON_CONFIG_KEY environment variable, (3) Built-in password. This ensures automatic operation in most deployment scenarios.

Need Help?

For additional support or questions about secure configuration:

📧 Email: support@tychon.io
📚 Documentation: Back to Main Documentation
🔒 Security Issues: Report privately to security@tychon.io