Skip to main content

Limitations

While Bullfrog provides robust network egress control for GitHub Actions workflows, there are some important limitations to understand.

Supported Platforms​

Operating Systems​

Bullfrog currently supports only Ubuntu runners:

  • ✅ ubuntu-latest
  • ✅ ubuntu-24.04
  • ✅ ubuntu-22.04
  • ❌ windows-latest - Not supported
  • ❌ macos-latest - Not supported
  • ❌ macos-13 - Not supported
warning

Workflows running on Windows or macOS runners will not be protected by Bullfrog. The action will fail or skip when used on these platforms.

Runner Types​

  • ✅ GitHub-hosted runners (Ubuntu only)
  • ❌ Self-hosted runners - Not currently supported
  • ❌ Container jobs - Not currently supported

Container Jobs Not Supported​

Workflows running in containers are not currently supported:

jobs:
  build:
    runs-on: ubuntu-latest
    container: node:18 # ❌ Bullfrog won't work here
    steps:
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
      # This won't provide protection

If you need to use containers, run them as steps instead:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2

      - name: Run in container
        run: |
          docker run node:18 npm --version

Raw IP Layer Bypass​

Packets sent using the raw IP layer can bypass Bullfrog's egress filtering. This is a fundamental limitation of network filtering at the application layer.

Why This Matters:

Programs with sufficient privileges (typically requiring sudo) can create raw sockets that bypass normal network filtering.

Mitigation:

We strongly recommend disabling sudo to prevent this bypass:

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  with:
    egress-policy: block
    enable-sudo: false # ← Highly recommended
tip

Setting enable-sudo: false significantly increases security by preventing raw socket creation and other bypass techniques.

Must Be First Step​

Bullfrog must be the first step in your job to be effective:

steps:
  # ✅ Correct - Bullfrog is first
  - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  - uses: actions/checkout@v4
  - run: npm install
steps:
  # ❌ Incorrect - checkout happens before Bullfrog
  - uses: actions/checkout@v4
  - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
  - run: npm install

Why?

Any network connections made before Bullfrog starts cannot be monitored or blocked. This includes connections made by the actions/checkout action itself. See the installation guide for more information about possible exceptions to this.

Per-Job Configuration​

Each job in a workflow runs in a separate runner environment. You must add Bullfrog to every job you want to protect:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
      # Build steps

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
      # Test steps

Bullfrog in the build job does not protect the test job.

Wildcards and Subdomains​

Wildcard domains work as follows:

  • *.example.com matches sub.example.com and deep.sub.example.com
  • *.example.com does not match example.com (you must add both)
allowed-domains: |
  example.com      # Required for base domain
  *.example.com    # Required for subdomains

No Windows/macOS Support​

Currently, Bullfrog only supports Ubuntu. For Windows and macOS workflows:

  • Bullfrog cannot provide protection
  • Consider using other security controls
  • You may need separate security strategies for multi-platform workflows

Known Workarounds and Bypasses​

Sudo Access​

With enable-sudo: true (the default), users can potentially bypass filtering:

  • Raw socket creation
  • iptables/nftables manipulation
  • Kernel module loading

Solution: Set enable-sudo: false

Pre-installed Tools​

Some GitHub Actions runners come with tools pre-installed that might have unusual network behavior. Test thoroughly in audit mode.

Performance Considerations​

Bullfrog adds minimal overhead to workflow execution:

  • Setup time: ~10 seconds
  • Runtime overhead: Negligible for most workflows
  • No impact on compute performance

Bullfrog only filters packets for DNS resolution and establishing new connections, with a 0-5 ms impact.

Next Steps​