agentsecops/sast-horusec

Horusec SAST Scanner

Overview

Horusec is an open-source security analysis tool that performs static code analysis across 18+ programming languages using 20+ integrated security tools. It identifies vulnerabilities during development, scans git history for exposed secrets, and integrates seamlessly into CI/CD pipelines for secure SDLC practices.

Supported Languages

C#, Java, Kotlin, Python, Ruby, Golang, Terraform, JavaScript, TypeScript, Kubernetes, PHP, C, HTML, JSON, Dart, Elixir, Shell, Nginx

Quick Start

Run Horusec scan on current project:

# Using Docker (recommended)
docker run -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd):/src horuszup/horusec-cli:latest horusec start -p /src -P $(pwd)

# Local installation
horusec start -p ./path/to/project

Core Workflows

Workflow 1: Local Security Scan

For developers performing pre-commit security analysis:

1. Navigate to project directory
2. Run Horusec scan:

   horusec start -p . -o json -O horusec-report.json
   

3. Review JSON output for vulnerabilities
4. Filter by severity (HIGH, MEDIUM, LOW, INFO)
5. Address critical and high-severity findings
6. Re-scan to validate fixes

Workflow 2: CI/CD Pipeline Integration

Progress: [ ] 1. Add Horusec to CI/CD pipeline configuration [ ] 2. Configure output format (JSON for automated processing) [ ] 3. Set severity threshold for build failures [ ] 4. Run scan on each commit or pull request [ ] 5. Parse results and fail build on high-severity findings [ ] 6. Generate security reports for audit trail [ ] 7. Track remediation progress over time

Work through each step systematically. Check off completed items.

Workflow 3: Git History Secret Scanning

For detecting exposed credentials and secrets:

1. Run Horusec with git history analysis enabled:

   horusec start -p . --enable-git-history-analysis
   

2. Review detected secrets and credentials
3. Rotate compromised credentials immediately
4. Add detected patterns to .gitignore and .horusec/config.json
5. Use git-filter-branch or BFG Repo-Cleaner to remove from history (if needed)
6. Document incident and update security procedures

Workflow 4: False Positive Management

When managing scan results and reducing noise:

1. Run initial scan and export results:

   horusec start -p . -o json -O results.json
   

2. Review findings and identify false positives
3. Create or update .horusec/config.json with ignore rules:

   {
     "horusecCliRiskAcceptHashes": ["hash1", "hash2"],
     "horusecCliFilesOrPathsToIgnore": ["**/test/**", "**/vendor/**"]
   }
   

4. Re-run scan to verify false positives are suppressed
5. Document risk acceptance decisions for compliance
6. Periodically review ignored findings

Configuration

Create .horusec/config.json in project root for custom configuration:

{
  "horusecCliCertInsecureSkipVerify": false,
  "horusecCliCertPath": "",
  "horusecCliContainerBindProjectPath": "",
  "horusecCliCustomImages": {},
  "horusecCliCustomRulesPath": "",
  "horusecCliDisableDocker": false,
  "horusecCliFalsePositiveHashes": [],
  "horusecCliFilesOrPathsToIgnore": [
    "**/node_modules/**",
    "**/vendor/**",
    "**/*_test.go",
    "**/test/**"
  ],
  "horusecCliHeaders": {},
  "horusecCliHorusecApiUri": "",
  "horusecCliJsonOutputFilePath": "./horusec-report.json",
  "horusecCliLogFilePath": "./horusec.log",
  "horusecCliMonitorRetryInSeconds": 15,
  "horusecCliPrintOutputType": "text",
  "horusecCliProjectPath": ".",
  "horusecCliRepositoryAuthorization": "",
  "horusecCliRepositoryName": "",
  "horusecCliReturnErrorIfFoundVulnerability": false,
  "horusecCliRiskAcceptHashes": [],
  "horusecCliTimeoutInSecondsAnalysis": 600,
  "horusecCliTimeoutInSecondsRequest": 300,
  "horusecCliToolsConfig": {},
  "horusecCliWorkDir": ".horusec"
}

Output Formats

Horusec supports multiple output formats for different use cases:

• text - Human-readable console output (default)
• json - Structured JSON for CI/CD integration
• sonarqube - SonarQube-compatible format

Specify with -o flag:

horusec start -p . -o json -O report.json

Common Patterns

Pattern 1: Fail Build on High Severity

Configure CI/CD to fail on critical findings:

horusec start -p . \
  --return-error-if-found-vulnerability \
  --severity-threshold="MEDIUM"

Exit code will be non-zero if vulnerabilities at or above threshold are found.

Pattern 2: Multi-Project Monorepo Scanning

Scan multiple projects in monorepo structure:

# Scan specific subdirectories
for project in service1 service2 service3; do
  horusec start -p ./$project -o json -O horusec-$project.json
done

Pattern 3: Custom Rules Integration

Add custom security rules:

1. Create custom rules file (YAML format)
2. Configure path in .horusec/config.json:

   {
     "horusecCliCustomRulesPath": "./custom-rules.yaml"
   }
   

3. Run scan with custom rules applied

Security Considerations

• Sensitive Data Handling: Horusec scans for exposed secrets. Ensure scan results are stored securely and access is restricted to authorized personnel only
• Access Control: Limit access to Horusec configuration files and scan results. Use read-only mounts in Docker for source code scanning
• Audit Logging: Log all scan executions, findings, and risk acceptance decisions for compliance auditing
• Compliance: Integrates with SOC2, PCI-DSS, and GDPR compliance by identifying vulnerabilities and tracking remediation
• Safe Defaults: Configure severity thresholds appropriate for your risk tolerance. Start with MEDIUM or HIGH to reduce noise

Integration Points

CI/CD Integration

GitHub Actions:

- name: Run Horusec Security Scan
  run: |
    docker run -v /var/run/docker.sock:/var/run/docker.sock \
      -v $(pwd):/src horuszup/horusec-cli:latest \
      horusec start -p /src -o json -O horusec-report.json \
      --return-error-if-found-vulnerability

GitLab CI:

horusec-scan:
  image: horuszup/horusec-cli:latest
  script:
    - horusec start -p . -o json -O horusec-report.json
  artifacts:
    reports:
      horusec: horusec-report.json

Jenkins:

stage('Security Scan') {
  steps {
    sh 'docker run -v $(pwd):/src horuszup/horusec-cli:latest horusec start -p /src'
  }
}

VS Code Extension

Horusec provides a VS Code extension for real-time security analysis during development. Install from VS Code marketplace.

Vulnerability Management

Horusec can integrate with centralized vulnerability management platforms via:

• JSON output parsing
• Horusec Platform (separate web-based management tool)
• Custom integrations using API

Troubleshooting

Issue: Docker Socket Permission Denied

Solution: Ensure Docker socket has proper permissions:

sudo chmod 666 /var/run/docker.sock
# Or run with sudo (not recommended for CI/CD)

Issue: False Positives in Test Files

Solution: Exclude test directories in configuration:

{
  "horusecCliFilesOrPathsToIgnore": ["**/test/**", "**/*_test.go", "**/tests/**"]
}

Issue: Scan Timeout on Large Repositories

Solution: Increase timeout values in configuration:

{
  "horusecCliTimeoutInSecondsAnalysis": 1200,
  "horusecCliTimeoutInSecondsRequest": 600
}

Issue: Missing Vulnerabilities for Specific Language

Solution: Verify language is supported and Docker images are available:

horusec version --check-for-updates
docker pull horuszup/horusec-cli:latest

Advanced Usage

Running Without Docker

Install Horusec CLI directly (requires all security tool dependencies):

# macOS
brew install horusec

# Linux
curl -fsSL https://raw.githubusercontent.com/ZupIT/horusec/main/deployments/scripts/install.sh | bash

# Windows
# Download from GitHub releases

Then run:

horusec start -p . --disable-docker

Note: Running without Docker requires manual installation of all security analysis tools (Bandit, Brakeman, GoSec, etc.)

Severity Filtering

Filter results by severity in output:

# Only show HIGH and CRITICAL
horusec start -p . --severity-threshold="HIGH"

# Show all findings
horusec start -p . --severity-threshold="INFO"

Custom Docker Images

Override default security tool images in configuration:

{
  "horusecCliCustomImages": {
    "python": "my-registry/custom-bandit:latest",
    "go": "my-registry/custom-gosec:latest"
  }
}

Report Analysis

Parse JSON output for automated processing:

# Extract high-severity findings
cat horusec-report.json | jq '.analysisVulnerabilities[] | select(.severity == "HIGH")'

# Count vulnerabilities by language
cat horusec-report.json | jq '.analysisVulnerabilities | group_by(.language) | map({language: .[0].language, count: length})'

# List unique CWE IDs
cat horusec-report.json | jq '[.analysisVulnerabilities[].securityTool] | unique'

References

• Horusec GitHub Repository
• Horusec Documentation
• OWASP Top 10
• CWE - Common Weakness Enumeration