GitHub On-Premises

To integrate Flyingduck with your GitHub Enterprise Server, you first need to register a GitHub App.

App Registration

Follow the steps below and provide the required details as instructed.

Create a New GitHub App

1. Sign in to your GitHub Enterprise Server as an administrator.
2. Navigate to: Settings → Developer settings → GitHub Apps → New GitHub App.

https://<your-github-onprem-domain>/settings/apps

3. Enter the following details:

   • GitHub App name: flyingduck
   • Homepage URL: https://app.flyingduck.io
   • Post-installation URL: https://app.flyingduck.io/integrations/github_onprem

Configure Webhook

1. In the Webhook section, provide the following:

   • Webhook URL: https://api.flyingduck.io/listeners/v1/github
   • Webhook secret: Ingore this

2. Ensure the webhook is active so that Flyingduck can receive events.

Set Permissions

Flyingduck requires specific permissions to access repositories, organizations, and accounts in order to provide full security monitoring and code scanning capabilities. Below is a summary of the permissions your GitHub App should have. Assign these carefully based on your organization’s security policies.

Repository Permissions: Flyingduck needs access to repository-level data, including actions, administration, checks, code scanning alerts, codespaces and their metadata, commit statuses, contents, deployments, discussions, environments, issues, merge queues, packages, pages, projects, pull requests, repository security advisories, secret scanning alerts, secrets, variables, and webhooks. These permissions allow Flyingduck to monitor activity, scan code, and provide actionable insights.

Organization Permissions: Flyingduck requires administrative access to manage members, teams, repository roles, events, organization announcements, codespaces, secrets, projects, and variables. It also requires access to personal access token requests and self-hosted runners. These permissions ensure Flyingduck can integrate seamlessly with organizational workflows and automate security checks across multiple repositories.

Account Permissions: At the user account level, Flyingduck requires minimal access including email addresses, SSH and GPG keys, codespaces user secrets, followers, interactions limits, plan details, and starring/watching activity. These are necessary for authentication, notifications, and personalized monitoring without compromising sensitive user data.

⚠️ Make sure to review and grant only the necessary permissions. Excessive access can pose security risks.

Subscribe to Events

Flyingduck relies on selected webhook events to track repository, organization, and account activity in real-time. Subscribing to the appropriate events ensures that Flyingduck can respond promptly to code changes, security alerts, and workflow updates.

Recommended events include:

Repository Events: push, pull request, pull request review, pull request review comment, pull request review thread, release, branch protection rule, repository ruleset, workflow dispatch, workflow run, repository metadata, commit comment, create, delete, fork, registry package.

Security & Analysis Events: security advisory, code scanning alert, check run, check suite, dependabot alert, secret scanning alert, secret scanning alert location, deployment, deployment review, deployment status, deployment protection rule.

Team & Membership Events: team, team add, member, membership, merge queue entry, merge group.

Organization & Account Events: organization, personal access token request, public, discussion, discussion comment, status.

⚠️ Subscribe only to the events relevant to your workflow. Unnecessary events may generate excess notifications and impact performance.

Register the App

1. Click Create GitHub App.

2. After registration, GitHub will generate:

   • App ID (used in API communication)
   • Client ID & Client Secret (if OAuth is enabled)

Generate Private Key

1. In the app settings, scroll to the Private keys section.
2. Click Generate a private key.
3. A .pem file will be downloaded – save this securely.

This key will be required when configuring Flyingduck Runner.

At this point, the Flyingduck GitHub App is registered in your GitHub Enterprise Server. You can now proceed to configure the integration within Flyingduck.

Integrating GitHub On-Prem with Flyingduck

Flyingduck allows you to connect your GitHub On-Premise instance for automated security monitoring and code scanning. Ensure your GitHub On-Prem instance is already registered before starting.

Access the Integration

1. Sign in to the Flyingduck portal as an administrator.
2. Navigate to Administration → Integrations.
3. Locate GitHub On-Prem and click Integrate.

Install App

1. Enter the URL of your GitHub On-Prem instance. Example placeholder: https://your-domain.com

2. Click Continue to establish the connection.

3. You will be redirected to the GitHub On-Prem app that you registered previously.

   • In the app, select the organization you want to integrate with Flyingduck.
   • Choose whether to install the app on all repositories or select repositories.
   • Permissions added during registration will be applied automatically.
   • Click Install to complete the process.

You will be redirected back to the Flyingduck portal to check the status of your installation. If successful, proceed to the next step. If not, contact our support team.

Active Branches

In the Active Branches section, specify the branches most frequently used in your environment. This ensures that code is scanned for vulnerabilities in early development environments, allowing issues to be identified and resolved before reaching production, where fixes can be more costly.

Click on Save and the branches are saved.

API Key

API Key is used to authenticate your GitHub with Flyingduck and send data to be shown in the portal. If you already have an API key available, you can click on Skip. Otherwise, you can create a new key by assigning a name to it and then clicking on Generate API key. Please note that within an organization, only two API Keys can be created. If you wish to create more, you will need to deactivate the previous ones.

Store the key confidentially as it will only be shown once. Click Next to proceed.

env:
  docker_tag: flyingduckio/duckdefender:latest
  
name: DuckDefender
 
on:
  push:
    branches:
      - "main"
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Download image from Docker Hub
      - name: Download latest DuckDefender
        run: docker pull "${{ env.docker_tag }}"
 
      # Run DuckDefender
      - name: Run DuckDefender
        env:
          FD_API_KEY: ${{ secrets.FD_API_KEY }}
          GITHUB_TOKEN: ${{ github.token }}
          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
          GITHUB_REPOSITORY_OWNER_ID: ${{ github.repository_owner_id }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_REPOSITORY_ID: ${{ github.repository_id }}
          GITHUB_EVENT_NAME: ${{ github.event_name }}
          GITHUB_ACTOR: ${{ github.actor }}
          GITHUB_ACTOR_ID: ${{ github.actor_id }}
          GITHUB_HEAD_REF: ${{ github.head_ref }}
          GITHUB_BASE_REF: ${{ github.base_ref }}
          GITHUB_REF: ${{ github.ref }}
          GITHUB_SHA: ${{ github.sha }}
          WORKSPACE_PATH: /src
          LOG_LEVEL: debug
 
        run: |
          docker run --pull=always -e GITHUB_REPOSITORY_OWNER="$GITHUB_REPOSITORY_OWNER" \
            -e GITHUB_REPOSITORY_OWNER_ID="$GITHUB_REPOSITORY_OWNER_ID" \
            -e GITHUB_REPOSITORY="$GITHUB_REPOSITORY" \
            -e GITHUB_REPOSITORY_ID="$GITHUB_REPOSITORY_ID" \
            -e GITHUB_EVENT_NAME="$GITHUB_EVENT_NAME" \
            -e GITHUB_ACTOR="$GITHUB_ACTOR" \
            -e GITHUB_ACTOR_ID="$GITHUB_ACTOR_ID" \
            -e FD_API_KEY="$FD_API_KEY" \
            -e GITHUB_TOKEN="$GITHUB_TOKEN" \
            -e GITHUB_HEAD_REF="$GITHUB_HEAD_REF" \
            -e GITHUB_BASE_REF="$GITHUB_BASE_REF" \
            -e GITHUB_REF="$GITHUB_REF" \
            -e GITHUB_SHA="$GITHUB_SHA" \
            -e WORKSPACE_PATH="$WORKSPACE_PATH" \
            -e LOG_LEVEL="$LOG_LEVEL" \
            -v "${{ github.workspace }}":/src "${{ env.docker_tag }}"
 

 
# Triggers the workflow on push events but only for the all the critical branches
on:
  push:
    branches: [ "master", "main", "release", "develop" , "feature/*" , "bug/*" ]

# Version: '2.1.2'
env:
  docker_tag: flyingduckio/duckdefender:latest
 
# This is a basic workflow to help you get started with GitHub Actions 
name: DuckDefender
 
# Triggers the workflow on push events but only for the all the critical branches
on:
  push:
    branches: [ "master", "main", "release", "develop" ]
  
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  build:
    runs-on: ubuntu-latest
 
# Steps represent a sequence of tasks that will be executed as part of the job
    steps:
    - uses: actions/checkout@v4
 
    # Download image from docker hub
 
    - name: Download latest DuckDefender
      run: docker pull "${{env.docker_tag}}"
 
    - name: Run DuckDefender
      run: |
        docker run -e GITHUB_REPOSITORY_OWNER="${{github.repository_owner}}" \
          -e GITHUB_REPOSITORY_OWNER_ID="${{github.repository_owner_id}}" \
          -e GITHUB_REPOSITORY="${{github.repository}}" \
          -e GITHUB_REPOSITORY_ID="${{github.repository_id}}" \
          -e GITHUB_EVENT_NAME="${{github.event_name}}" \
          -e GITHUB_ACTOR="${{github.actor}}" \
          -e GITHUB_ACTOR_ID="${{github.actor_id}}" \
          -e FD_API_KEY="${{secrets.FD_API_KEY}}" \
          -e GITHUB_TOKEN="${{github.token}}" \
          -e GITHUB_HEAD_REF="${{github.head_ref}}" \
          -e GITHUB_BASE_REF="${{github.base_ref}}" \
          -e GITHUB_REF="${{github.ref}}" \
          -e GITHUB_SHA="${{github.sha}}" \
          -e WORKSPACE_PATH="/src" \
          -e LOG_LEVEL="debug" \
          -v "${{ github.workspace }}":/src  "${{env.docker_tag}}"

Comparison with On-Premise runner

GitHub workflows run based on the allocated minutes. Once these minutes are consumed, workflows will stop, and code scans cannot be performed.

Additionally, workflows are triggered only when a commit is made. On-demand code scans are not possible.

Workflows operate on the branches listed in the duckdefender.yml file. New branches and pushed code to these new branches will not be scanned unless the duckdefender.yml file is updated each time. To address the above limitation, we have introduced another feature called the On-Premise runner.

On-premise Runner

This step can also be configured prior to starting the integration process.

Automated Scan

After selecting the scanning option, enable the checkbox to automatically scan the code upon each commit. This functionality is available only when a runner is configured and active.

CLI Integration

This integration provides a simple way to scan your codebase without doing any UI configuration.

Steps to Integrate:

1. Copy Your Flyingduck API Key:
   Retrieve your API key from the Flyingduck portal. This is essential for authentication during scanning.

2. Clone Your Repository:
   Open your terminal and run: git clone <your-repository-url>

   Navigate into the cloned repository directory: cd <your-repo-folder>

3. Run the Docker Command:
   Execute the following command to start the scan:

   docker run -e FD_API_KEY=<your-api-key> -v ${PWD}:/src --entrypoint /bin/bash flyingduckio/duckdefender:latest -c "duckdefender code --all"

   Replace <your-api-key> with the actual API key copied earlier.

4. View Scan Results:
   The HEAD commit of the repository is scanned. Results, including potential security issues, will be displayed directly in the Flyingduck portal dashboard.

For advanced configurations and additional flags, visit the Flyingduck CLI documentation (opens in a new tab).

This streamlined guide aims to get you scanning quickly with Flyingduck, leveraging Docker and your API key for effortless security integration.