Skip to main content

Configuration Reference

Bullfrog provides several configuration options to customize how network egress is controlled in your GitHub Actions workflows.

Configuration Options​

allowed-ips​

List of IP addresses to allow outbound connections to. Use this to allow DNS query via custom DNS servers.

  • Type: Multi-line string
  • Required: No
  • Default: Localhost and IPs required for GitHub Actions essential operations

Example:

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    allowed-ips: |
      1.2.3.4
      5.6.7.8
      192.168.1.0/24

Example with custom DNS server:

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    allowed-ips: |
      100.100.100.100 # Tailscale Magic DNS

allowed-domains​

List of domains to allow outbound connections to. Wildcards are supported.

  • Type: Multi-line string
  • Required: No
  • Default: Domains required for GitHub Actions essential operations and job summaries

Wildcard Behavior:

  • *.google.com matches www.google.com and console.cloud.google.com
  • *.google.com does not match google.com (you need to add both if needed)

Example:

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    allowed-domains: |
      github.com
      *.github.com
      registry.npmjs.org
      *.cloudfront.net

dns-policy​

Controls how DNS requests are handled when egress-policy is set to block.

  • Type: String
  • Required: No
  • Default: allowed-domains-only
  • Options:
    • allowed-domains-only: Only allow DNS resolution for domains in allowed-domains
    • any: Allow DNS resolution for any domain
Security Note

Setting this to allowed-domains-only is highly recommended for security. Data can be exfiltrated outside your network using DNS exfiltration.

Important Consideration:

If you're allowing connections to specific IPs using allowed-ips, but your workflow accesses those services via domain names (e.g., curl https://api.example.com), you must set dns-policy: any to allow DNS resolution for those domains. Otherwise, the DNS lookup will be blocked even though the resulting IP is in your allow list.

If you only want to control egress via IPs and not domains, you must use dns-policy: any, but be aware this comes with DNS exfiltration risks.

Example:

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    egress-policy: block
    allowed-ips: |
      1.2.3.4
    dns-policy: any # Required if accessing services by domain name that resolve to allowed IPs

egress-policy​

The primary policy that controls whether connections are blocked or only audited.

  • Type: String
  • Required: No
  • Default: audit
  • Options:
    • audit: Log all outbound connections without blocking (recommended to start)
    • block: Block connections that don't match allowed IPs/domains

Example:

# Start with audit mode
- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    egress-policy: audit

# Then switch to block mode when ready
- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    egress-policy: block
    allowed-domains: |
      github.com
      *.npmjs.org

enable-sudo​

Controls whether steps can execute commands with sudo privileges.

  • Type: Boolean
  • Required: No
  • Default: true
  • Options: true or false
Security Note

Setting this to false is highly recommended for security. Raw IP layer packets can bypass Bullfrog's filtering, and sudo access could enable such bypass techniques.

Example:

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    egress-policy: block
    enable-sudo: false # Recommended for maximum security

Complete Configuration Example​

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    # Enforce blocking policy
    egress-policy: block

    # Allow specific domains
    allowed-domains: |
      github.com
      *.github.com
      registry.npmjs.org
      *.docker.com
      docker.io
      *.docker.io

    # Allow specific IPs
    allowed-ips: |
      1.2.3.4
      192.168.1.0/24

    # Restrict DNS to allowed domains only
    dns-policy: allowed-domains-only

    # Disable sudo for maximum security
    enable-sudo: false

Default Allowed Connections​

Even without any configuration, Bullfrog allows connections essential for GitHub Actions to function:

  • Localhost (127.0.0.1)
  • GitHub infrastructure (required for Actions runtime)
  • Job summary uploads (required for reporting blocked connections)

These defaults ensure Bullfrog doesn't break your workflows while providing security controls.

Configuration Best Practices​

  1. Start with Audit Mode: Always begin with egress-policy: audit to discover what connections your workflow needs
  2. Review Workflow Summaries: Check the workflow summary for logged connections
  3. Create Minimal Allow Lists: Only add the specific domains/IPs your workflow requires
  4. Use Wildcards Carefully: Wildcards can be convenient but may allow more than intended
  5. Disable Sudo: Set enable-sudo: false unless your workflow specifically needs elevated privileges
  6. Pin to Commit SHA: Use the full commit SHA instead of tags for maximum security

Next Steps​