Creating and tracking security campaigns

Creating a security campaign

Security campaigns are created and managed from the Security tab for your organization. You choose the alerts to include in a campaign by selecting a campaign template from the sidebar of the "Overview" dashboard or by filtering the alerts displayed on the code scanning alerts view for your organization.

For more information about filtering alerts, see Best practices for fixing security alerts at scale and Filtering alerts in security overview.

Creating a campaign from a template

The campaign templates contain filters for the most common alert selections. They also all include the requirement that GitHub Copilot Autofix is supported for all the alert types included (that is, autofix:supported).

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Security.

   

3. In the left sidebar, next to "Campaigns", click the icon to start creating a campaign.

4. Select one of the pre-defined filter templates to open a "New campaign from TEMPLATE_NAME template" dialog box.

5. If the message "This looks like a big campaign" is displayed, click Back to filters to display the code scanning alerts view with the campaign template filter shown.

   1. Add further filters to reduce the number of alerts shown, for example, filtering by "Team" or by custom property.
   2. When there are fewer than 1000 alerts in 100 repositories, click Create campaign to redisplay the "New campaign" dialog.

   Alternatively, you can click Continue creating a campaign and create the campaign. Alerts will be omitted to until there are fewer than 1000 alerts in fewer than 100 repositories remaining. Alerts in repositories with recent pushes are prioritized for inclusion in the campaign.

6. Edit the "Campaign name" and "Short description" to match your campaign needs and to link to any resources that support the campaign.

7. Define a "Campaign due date" and select a "Campaign manager" as the primary contact for the campaign (an owner or security manager of this organization).

8. When you're ready to create the campaign, click Create campaign.

The security campaign is created and the campaign overview page is displayed.

Creating a campaign using custom filters

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Security.

   

3. In the left sidebar, under "Alerts" click Code scanning to show the alerts view.

4. Add filters to select a subset of alerts for your campaign. When you have chosen fewer than 1000 alerts, spread across fewer than 100 repositories, you are ready to create a campaign.

5. Above the table of alerts, click Create campaign to start creating a campaign.

6. If the message "This looks like a big campaign" is displayed, click Back to filters to display the code scanning alerts view with your existing filters.

   1. Add further filters to reduce the number of alerts shown, for example, filtering by "Team" or by custom property.
   2. When there are fewer than 1000 alerts in 100 repositories, click Create campaign to redisplay the "New campaign" dialog.

   Alternatively, you can click Continue creating a campaign and create the campaign. Alerts will be omitted to until there are fewer than 1000 alerts in fewer than 100 repositories remaining. Alerts in repositories with recent pushes are prioritized for inclusion in the campaign.

7. Edit the "Campaign name" and "Short description" to match your campaign needs and to link to any resources that support the campaign.

8. Define a "Campaign due date" and select a "Campaign manager" as the primary contact for the campaign (an owner or security manager of this organization).

9. When you're ready to create the campaign, click Create campaign.

Examples of useful filters

All the template filters include the following useful filters:

• is:open includes only alerts that are open in the default branch.
• autofilter:true includes only alerts that appear to be in application code.
• autofix:supported includes only alerts that are for rules that are supported for GitHub Copilot Autofix.

Once you include these core filters, you will usually want to add a filter to limit results to a specific rule name, severity, or tag. For example:

• is:open autofilter:true autofix:supported rule:java/log-injection to show only alerts for log injection in Java code.
• is:open autofilter:true autofix:supported tag:external/cwe/cwe-117 to show only alerts for "CWE 117: Improper Output Neutralization for Logs". This includes log injection in Java and other languages.
• is:open autofilter:true autofix:supported severity:critical to show only alerts with a security severity of critical

For more information about the rules run by CodeQL and support for autofix, see Query lists for the default query suites.

Launching a security campaign

When you create a campaign all the alerts are automatically submitted to GitHub Copilot Autofix to be processed as capacity allows. This ensures that suggestions for alerts found in pull requests aren't delayed by a new campaign. In most cases, you should find that all suggestions that can be created are ready within an hour. At busy times of day, or for particularly complex alerts, it will take longer.

How developers know a security campaign has started

Everyone with write access to a repository that is included in the campaign is notified, according to their notification preferences, about the campaign.

In addition to the automatic notifications sent out, the new campaign is shown in the sidebar of the "Security" tab for each repository included. For more information about the developer experience, see Fixing alerts in a security campaign.

How to increase engagement with the security campaign

The best way to increase engagement with a campaign is to publicize it to the teams you want to collaborate with to remediate alerts. For example, you might work with engineering managers to choose a quieter development period to run a series of security campaigns, each focused on a different type of alert, with associated training sessions. For more ideas, see Best practices for fixing security alerts at scale.

Tracking security campaigns

When you create a campaign, the campaign tracking view is displayed and the campaign is listed in the sidebar of the Security tab for the organization. You can redisplay the campaign tracking view at any time by selecting it in the sidebar under "Campaigns".

Security campaign alert statuses

The summary at the top of the campaign view reports the number of alerts closed, open, and in progress.

• In progress when at least one branch or pull request is created to fix the alert through the campaign view or the alert page.
• Closed when the alert is fixed or dismissed, even if the development work was done outside the campaign framework.

Security campaign views

You can explore the campaign repositories and alerts to see where teams are engaging in the campaign, and where teams might need some extra encouragement to take part.

• Repository details: you can expand any repository to show the progress in alert remediation.
• Alert details: you can set the "Group by" option to None to show a list of all alerts.

You can filter both of these views to focus on a subset of repositories or alerts. Any alerts that are in progress are listed first.

Editing security campaign details

You can edit the name, description, due date, and manager for a campaign. This is particularly useful if the current campaign manager is on leave and you need to define a new contact for developers.

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Security.

   

3. In the sidebar, under "Campaigns" click the name of the campaign to display the campaign tracking view.

4. In the campaign title row, click and select Edit campaign.

5. In the "Edit campaign" dialog make your changes and then click Save changes.

The changes are made immediately.

Closing or deleting security campaigns

There is a limit of 10 active campaigns. When a campaign is complete, or if you want to pause it, you should close it. When you close a campaign, it's no longer displayed for developers in the repository Security tab but you can still display the campaign tracking view to develop best practice. In addition, you can reopen a closed campaign from the "Closed campaigns" view, which is accessible from the sidebar in the Security tab of the organization.

If you open a campaign for testing, you may prefer to delete the campaign. This deletes the campaign and all associated data entirely.

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Security.

   

3. In the sidebar, under "Campaigns" click the name of the campaign to display the campaign tracking view.

4. In the campaign title row, click and select your required option:

   • Close campaign to remove it from the active campaigns list and display it on the Closed campaigns view.
   • Delete campaign to delete the campaign permanently. In the "Delete campaign" dialog, click Delete to confirm that you want to delete the campaign.