CA Cert

Stoobly CA Certificate CLI - Questions & Answers

The CA certificate CLI manages SSL/TLS certificate authority operations for intercepting HTTPS traffic. Installing the CA certificate allows Stoobly to decrypt and inspect HTTPS requests for recording, mocking, and testing.

Understanding CA Certificates

Q: What is a CA certificate?

A: A CA (Certificate Authority) certificate is a root certificate that allows Stoobly to create valid SSL certificates for intercepting HTTPS traffic. It enables the proxy to decrypt, inspect, and re-encrypt HTTPS requests.

Example:

# Install CA certificate to enable HTTPS interception
stoobly-agent ca-cert install

Q: Why do I need to install a CA certificate?

A: Installing the CA certificate allows Stoobly to intercept HTTPS traffic. Without it, you can only record and mock HTTP (non-encrypted) requests.

Example:

# Without CA cert: Only HTTP works
stoobly-agent record http://api.example.com/users

# With CA cert: Both HTTP and HTTPS work
stoobly-agent ca-cert install
stoobly-agent record https://api.example.com/users  # Now works!

Q: Is it safe to install the CA certificate?

A: Yes, the CA certificate is only installed on your local machine and is only trusted by your system. It's used solely for local development and testing. Remove it when done with ca-cert uninstall.

Example:

# Install for testing
stoobly-agent ca-cert install

# When done, uninstall
stoobly-agent ca-cert uninstall

Installing CA Certificate

Q: How do I install the CA certificate?

A: Use ca-cert install to install the certificate authority certificate on your system.

Example:

stoobly-agent ca-cert install

Q: Where does the CA certificate get installed?

A: The CA certificate is installed in your system's trusted certificate store. The location varies by operating system:

  • macOS: Keychain Access

  • Linux: /usr/local/share/ca-certificates/ or system store

  • Windows: Certificate Manager

Example:

# Install CA cert
stoobly-agent ca-cert install

# On macOS, verify in Keychain Access
open -a "Keychain Access"
# Search for "stoobly" or "mitmproxy"

# On Linux, check system certificates
ls /usr/local/share/ca-certificates/

Q: Do I need sudo/admin privileges to install the CA certificate?

A: Yes, installing system certificates typically requires administrative privileges.

Example:

# May prompt for password
stoobly-agent ca-cert install

# On Linux, might need sudo
sudo stoobly-agent ca-cert install

Q: How do I install the CA certificate to a custom directory?

A: Use the --ca-certs-dir-path option to specify where the CA certificate files are stored.

Example:

# Install from custom directory
stoobly-agent ca-cert install --ca-certs-dir-path /path/to/custom/ca-certs

Q: What happens during CA certificate installation?

A: The installation process creates the CA certificate (if not exists), adds it to your system's trust store, and configures it to be trusted for SSL/TLS connections.

Example:

stoobly-agent ca-cert install
# Output:
# Generating CA certificate...
# Installing CA certificate to system trust store...
# CA certificate installed successfully!

Creating SSL Certificates

Q: How do I create an SSL certificate for a hostname?

A: Use ca-cert mkcert with the hostname to generate a signed certificate.

Example:

# Create certificate for a domain
stoobly-agent ca-cert mkcert api.example.com

Q: How do I create certificates for multiple hostnames?

A: Run mkcert for each hostname you need to intercept.

Example:

# Create certificates for multiple domains
stoobly-agent ca-cert mkcert api.example.com
stoobly-agent ca-cert mkcert frontend.example.com
stoobly-agent ca-cert mkcert admin.example.com

Q: How do I create a wildcard certificate?

A: Use wildcard notation with the asterisk (*) for the subdomain.

Example:

# Wildcard certificate for all subdomains
stoobly-agent ca-cert mkcert "*.example.com"

# Now works for: api.example.com, app.example.com, etc.

Q: Where are the generated certificates stored?

A: Certificates are stored in the certs directory (default: ~/.stoobly/certs/).

Example:

# Create certificate (stored in default location)
stoobly-agent ca-cert mkcert api.example.com

# Check generated certificates
ls ~/.stoobly/certs/
# api.example.com.pem
# api.example.com-key.pem

Q: How do I specify a custom output directory for certificates?

A: Use the --certs-dir-path option to specify where certificates should be saved.

Example:

stoobly-agent ca-cert mkcert api.example.com --certs-dir-path /path/to/output

Q: How do I specify a custom CA certs directory?

A: Use the --ca-certs-dir-path option to use a different CA certificate for signing.

Example:

stoobly-agent ca-cert mkcert api.example.com \
  --ca-certs-dir-path /path/to/ca-certs \
  --certs-dir-path /path/to/output

Uninstalling CA Certificate

Q: How do I uninstall the CA certificate?

A: Use ca-cert uninstall to remove the certificate from your system (coming soon).

Example:

# Uninstall CA certificate
stoobly-agent ca-cert uninstall
# Output: Not yet implemented. Stay tuned!

Q: How do I manually remove the CA certificate?

A: Manually remove it from your system's certificate store until uninstall is implemented.

Example:

# macOS: Use Keychain Access
# 1. Open Keychain Access
# 2. Search for "stoobly" or "mitmproxy"
# 3. Delete the certificate

# Linux: Remove from certificate directory
sudo rm /usr/local/share/ca-certificates/stoobly-ca.crt
sudo update-ca-certificates

# Windows: Use Certificate Manager (certmgr.msc)
# 1. Open Certificate Manager
# 2. Navigate to Trusted Root Certification Authorities
# 3. Find and delete the Stoobly/mitmproxy certificate

Workflow Integration

Q: When should I install the CA certificate?

A: Install it before recording or testing HTTPS traffic. It's typically done once per machine during initial setup.

Example:

# Initial setup
stoobly-agent ca-cert install

# Now you can record HTTPS
stoobly-agent run --intercept --intercept-mode record

Q: How do I use CA certificates with scaffold workflows?

A: The scaffold workflow automatically prompts for CA certificate installation when needed.

Example:

# Start scaffold workflow
stoobly-agent scaffold workflow up record --app-dir-path ./my-app
# Prompt: Installing CA certificate is required for recording requests, continue? (y/N)

# Or skip prompt with environment variable
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
stoobly-agent scaffold workflow up record --app-dir-path ./my-app

# Or using Makefile
make -f .stoobly/services/.Makefile record

Q: How do I verify the CA certificate is installed?

A: Try recording HTTPS traffic. If it works without certificate errors, the CA cert is properly installed.

Example:

# Test HTTPS recording
stoobly-agent run --intercept --intercept-mode record

# In another terminal, try recording HTTPS
stoobly-agent record https://api.example.com/test

# If successful, CA cert is working

Troubleshooting

Q: What do I do if HTTPS recording fails?

A: Ensure the CA certificate is installed and trusted by your system.

Example:

# Reinstall CA certificate
stoobly-agent ca-cert install

# Check if certificate exists
ls ~/.mitmproxy/
# Should see: mitmproxy-ca.pem, mitmproxy-ca-cert.pem

# Try recording again
stoobly-agent record https://api.example.com/users

Q: What if I get SSL verification errors?

A: The CA certificate may not be properly trusted. Reinstall or manually verify in your system's certificate store.

Example:

# Reinstall
stoobly-agent ca-cert install

# On macOS, verify trust settings in Keychain Access
open -a "Keychain Access"
# Find certificate → Get Info → Trust → "Always Trust"

# On Linux, update certificates
sudo update-ca-certificates

Q: How do I handle multiple CA certificates?

A: Use different --ca-certs-dir-path for different projects or environments.

Example:

# Project A
stoobly-agent ca-cert install --ca-certs-dir-path ~/project-a/.stoobly/ca_certs

# Project B
stoobly-agent ca-cert install --ca-certs-dir-path ~/project-b/.stoobly/ca_certs

# Use with specific project
stoobly-agent run --ca-certs-dir-path ~/project-a/.stoobly/ca_certs

Q: What do I do if certificate installation fails?

A: Check for permission issues, ensure the directory exists, and verify you have admin privileges.

Example:

# Create directory if missing
mkdir -p ~/.stoobly/ca_certs

# Try with sudo (Linux)
sudo stoobly-agent ca-cert install

# Check for errors
stoobly-agent ca-cert install --ca-certs-dir-path ~/.stoobly/ca_certs

Browser Configuration

Q: Do I need to configure my browser after installing the CA certificate?

A: Most browsers use the system certificate store, but some (like Firefox) use their own. You may need to import the certificate manually.

Example:

# For Firefox:
# 1. Go to Settings → Privacy & Security → Certificates → View Certificates
# 2. Click "Import"
# 3. Select: ~/.mitmproxy/mitmproxy-ca-cert.pem
# 4. Trust for identifying websites

Q: How do I test if my browser trusts the CA certificate?

A: Start Stoobly proxy and visit an HTTPS site through it. If no certificate warning appears, it's working.

Example:

# Start proxy
stoobly-agent run --headless

# Configure browser proxy to localhost:8080
# Visit: https://example.com
# No certificate warning = CA cert is trusted

Team Collaboration

Q: Do team members need to install the CA certificate?

A: Yes, each team member needs to install the CA certificate on their machine to intercept HTTPS traffic.

Example:

# Each team member runs:
stoobly-agent ca-cert install

# Now everyone can record/test HTTPS

Q: Can I share CA certificate files with my team?

A: You can share the CA certificate files, but each team member still needs to install them on their system.

Example:

# Share via git (optional - for custom CA)
git add .stoobly/ca_certs/
git commit -m "Add shared CA certificate"

# Team members install
git pull
stoobly-agent ca-cert install --ca-certs-dir-path ./.stoobly/ca_certs

Q: Should CA certificates be committed to version control?

A: Generally no, as they're generated per machine. However, for team consistency, you can share a common CA certificate by committing it.

Example:

# .gitignore (typical setup)
.stoobly/ca_certs/  # Don't commit

# OR for team sharing:
# Remove .stoobly/ca_certs/ from .gitignore
# Commit shared CA certificate
git add .stoobly/ca_certs/
git commit -m "Add shared CA certificate for team"

CI/CD Integration

Q: How do I handle CA certificates in CI/CD?

A: Install the CA certificate in the CI environment before running tests.

Example:

#!/bin/bash
# CI/CD script

# Install CA certificate
stoobly-agent ca-cert install --ca-certs-dir-path ./ci-ca-certs

# Run tests with HTTPS
stoobly-agent run --intercept --intercept-mode test &
AGENT_PID=$!

# Wait for agent to start
sleep 2

# Run test suite
npm test

# Cleanup
kill $AGENT_PID

Q: How do I use certificates in Docker containers?

A: Mount the CA certificate directory and install it in the container.

Example:

# Dockerfile
FROM python:3.11

# Install stoobly-agent
RUN pip install stoobly-agent

# Copy CA certificate
COPY .stoobly/ca_certs /app/.stoobly/ca_certs

# Install CA certificate
RUN stoobly-agent ca-cert install --ca-certs-dir-path /app/.stoobly/ca_certs

# Run your application
CMD ["your-app"]

Security Considerations

Q: Is the CA certificate secure?

A: The CA certificate is only trusted on your local machine. However, anyone with access to the private key could intercept your HTTPS traffic, so protect the certificate files.

Example:

# Protect CA certificate files
chmod 600 ~/.mitmproxy/mitmproxy-ca.pem
chmod 600 ~/.mitmproxy/mitmproxy-ca-cert.pem

# Don't share private keys publicly
echo ".stoobly/ca_certs/" >> .gitignore

Q: Should I use the same CA certificate in production?

A: No! The CA certificate is for local development and testing only. Never use it in production environments.

Example:

# Development only
stoobly-agent ca-cert install

# Production: Use proper SSL certificates from trusted CAs
# (Let's Encrypt, DigiCert, etc.)

Q: How do I rotate CA certificates?

A: Delete old certificates and generate new ones.

Example:

# Remove old CA certificate
rm -rf ~/.mitmproxy/
rm -rf ~/.stoobly/ca_certs/

# Generate and install new one
stoobly-agent ca-cert install

# Regenerate host certificates
stoobly-agent ca-cert mkcert api.example.com

Quick Reference

Q: What are the most common ca-cert commands?

A: Here's a quick reference of frequently used commands:

Example:

# Install CA certificate (required for HTTPS)
stoobly-agent ca-cert install

# Install to custom directory
stoobly-agent ca-cert install --ca-certs-dir-path /path/to/ca-certs

# Create certificate for hostname
stoobly-agent ca-cert mkcert api.example.com

# Create wildcard certificate
stoobly-agent ca-cert mkcert "*.example.com"

# Create certificate with custom paths
stoobly-agent ca-cert mkcert api.example.com \
  --ca-certs-dir-path /path/to/ca-certs \
  --certs-dir-path /path/to/output

# Uninstall CA certificate (coming soon)
stoobly-agent ca-cert uninstall

Complete Setup Example

Q: What's the complete workflow for setting up CA certificates?

A: Install CA cert → Create host certificates → Configure proxy → Test HTTPS.

Example:

# Step 1: Install CA certificate
stoobly-agent ca-cert install

# Step 2: Create certificates for your domains (optional, auto-generated by proxy)
stoobly-agent ca-cert mkcert api.example.com
stoobly-agent ca-cert mkcert "*.myapp.local"

# Step 3: Start Stoobly proxy
stoobly-agent run --intercept --intercept-mode record

# Step 4: Configure your app to use proxy (localhost:8080)
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

# Step 5: Make HTTPS requests (they get intercepted)
curl https://api.example.com/users

# Step 6: View recorded requests
stoobly-agent request list

Platform-Specific Notes

Q: Are there any macOS-specific considerations?

A: On macOS, you may need to approve the certificate in Keychain Access and restart your browser.

Example:

# Install on macOS
stoobly-agent ca-cert install

# Open Keychain Access to verify
open -a "Keychain Access"

# Find "mitmproxy" certificate
# Double-click → Trust → "Always Trust"
# Close Keychain Access (it saves automatically)

# Restart browsers for changes to take effect

Q: Are there any Linux-specific considerations?

A: On Linux, you may need to update the certificate store after installation.

Example:

# Install on Linux
sudo stoobly-agent ca-cert install

# Update certificate store
sudo update-ca-certificates

# For Firefox, import manually
# Settings → Privacy & Security → Certificates → View Certificates → Import
# Select: ~/.mitmproxy/mitmproxy-ca-cert.pem

Q: Are there any Windows-specific considerations?

A: On Windows, you may need to run the command prompt as Administrator.

Example:

# Run Command Prompt as Administrator
# Right-click → "Run as administrator"

# Install CA certificate
stoobly-agent ca-cert install

# Certificate is added to Windows Certificate Store
# View: certmgr.msc → Trusted Root Certification Authorities
PreviousFAQNextConfig

Last updated

Was this helpful?