Skip to content

troubleshooting.md

Latest commit

 

History

History
115 lines (86 loc) · 3.75 KB

troubleshooting.md

File metadata and controls

115 lines (86 loc) · 3.75 KB

Troubleshooting

SSL certificate errors (CERTIFICATE_VERIFY_FAILED)

Cause: Corporate proxy (Zscaler, Netskope, etc.) intercepts HTTPS and uses its own CA certificate that Python doesn't trust.

How it works: AppSecOne's SSL resolution order is:

  1. SSL_CERT_FILE / REQUESTS_CA_BUNDLE env var (explicit override)
  2. certifi package (ships Mozilla CA bundle)
  3. macOS system keychain (automatic — includes corporate CAs)
  4. Python default

In most corporate environments, setting SSL_CERT_FILE is the most reliable fix.

macOS / Linux

# Export corporate CA certificates (macOS)
security find-certificate -a -p \
  /Library/Keychains/System.keychain \
  /System/Library/Keychains/SystemRootCertificates.keychain \
  > ~/combined-ca-bundle.pem

# On Linux, the CA bundle is usually at:
#   /etc/ssl/certs/ca-certificates.crt          (Debian/Ubuntu)
#   /etc/pki/tls/certs/ca-bundle.crt            (RHEL/Fedora)
# If your proxy adds its own CA, ask IT for the .pem and append:
#   cat corporate-ca.pem >> ~/combined-ca-bundle.pem

# Configure SSL trust (add to ~/.zshrc or ~/.bashrc)
export SSL_CERT_FILE=~/combined-ca-bundle.pem
export REQUESTS_CA_BUNDLE=~/combined-ca-bundle.pem

# (Optional) Configure git too
git config --global http.sslCAInfo ~/combined-ca-bundle.pem

Windows (PowerShell)

# Ask IT for the corporate CA .pem file, or export from certmgr.msc
# → Trusted Root CAs → Certificates → Export → Base-64 (.CER)

$env:SSL_CERT_FILE = "$env:USERPROFILE\corporate-ca-bundle.pem"
$env:REQUESTS_CA_BUNDLE = "$env:USERPROFILE\corporate-ca-bundle.pem"

# (Optional) Persist permanently
[System.Environment]::SetEnvironmentVariable("SSL_CERT_FILE", "$env:USERPROFILE\corporate-ca-bundle.pem", "User")

Disable SSL verification (development only)

In appsecone.json, set:

{
  "fortify": {
    "verify_ssl": false
  }
}

Or set environment variable:

export FORTIFY_SSL_VERIFY=false

⚠️ Warning: Disabling SSL verification exposes you to man-in-the-middle attacks. Only use for development with self-signed certificates.

Proxy configuration

AppSecOne respects standard proxy environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example.com

No additional AppSecOne configuration is needed.

Fortify SSC connection issues

Symptom Cause Fix
SSL: CERTIFICATE_VERIFY_FAILED Corporate proxy CA Set SSL_CERT_FILE (see above)
Connection refused Wrong URL or firewall Check fortify.base_url in config
401 Unauthorized Invalid or expired token Regenerate token in Fortify SSC
403 Forbidden Insufficient permissions Token needs API read access
Connection timed out Network/VPN issue Check VPN connection, try curl
Rate limited (429) Too many requests Reduce fortify.rate_limit_rps

Database issues

AppSecOne uses SQLite with WAL mode. If the database becomes corrupted:

# Remove and let AppSecOne recreate it
rm data/appsecone.db*
appsecone serve

Common environment variables

Variable Purpose Default
APPSECONE_FORTIFY_TOKEN Fortify SSC auth token (required)
SSL_CERT_FILE Path to CA certificate bundle (auto-detected)
REQUESTS_CA_BUNDLE Alternative CA bundle path (auto-detected)
FORTIFY_CA_BUNDLE Fortify-specific CA bundle (falls back to SSL_CERT_FILE)
HTTP_PROXY / HTTPS_PROXY Proxy server URL (none)
NO_PROXY Hosts to bypass proxy (none)
APPSECONE_API_KEY API key for admin endpoints (disabled)
APPSECONE_CORS_ORIGINS Allowed CORS origins (none)