REST API endpoints for security campaigns
Use the REST API to create and manage security campaigns for your organization.
Remarque
These endpoints only interact with published campaigns. Draft campaigns cannot currently be viewed or managed through the API.
List campaigns for an organization
Lists campaigns in an organization.
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint.
Jetons d’accès affinés pour « List campaigns for an organization »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
- Jetons d’accès utilisateur d’application GitHub
- Jetons d’accès d’installation d’application GitHub
- Jetons d’accès personnel affiné
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Campaigns" organization permissions (read)
Paramètres pour « List campaigns for an organization »
Nom, Type, Description |
---|
accept string Setting to |
Nom, Type, Description |
---|
org string ObligatoireThe organization name. The name is not case sensitive. |
Nom, Type, Description |
---|
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
direction string The direction to sort the results by. Default: Peut être: |
state string If specified, only campaigns with this state will be returned. Peut être: |
sort string The property by which to sort the results. Default: Peut être: |
Codes d’état de la réponse HTTP pour « List campaigns for an organization »
Code d’état | Description |
---|---|
200 | OK |
404 | Resource not found |
503 | Service unavailable |
Exemples de code pour « List campaigns for an organization »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com
par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com
.
Exemple de requête
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/campaigns
Response
Status: 200
[
{
"number": 3,
"created_at": "2024-02-14T12:29:18Z",
"updated_at": "2024-02-14T12:29:18Z",
"name": "Critical CodeQL alert",
"description": "Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.",
"managers": [
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
}
],
"ends_at": "2024-03-14T12:29:18Z",
"closed_at": null,
"state": "open"
},
{
"number": 4,
"created_at": "2024-03-30T12:29:18Z",
"updated_at": "2024-03-30T12:29:18Z",
"name": "Mitre top 10 KEV",
"description": "Remediate the MITRE Top 10 KEV (Known Exploited Vulnerabilities) to enhance security by addressing vulnerabilities actively exploited by attackers. This reduces risk, prevents breaches and can help protect sensitive data.",
"managers": [
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
}
],
"ends_at": "2024-04-30T12:29:18Z",
"closed_at": null,
"state": "open"
}
]
Create a campaign for an organization
Create a campaign for an organization.
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint.
Fine-grained tokens must have the "Code scanning alerts" repository permissions (read) on all repositories included in the campaign.
Jetons d’accès affinés pour « Create a campaign for an organization »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
- Jetons d’accès utilisateur d’application GitHub
- Jetons d’accès d’installation d’application GitHub
- Jetons d’accès personnel affiné
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Campaigns" organization permissions (write)
Paramètres pour « Create a campaign for an organization »
Nom, Type, Description |
---|
accept string Setting to |
Nom, Type, Description |
---|
org string ObligatoireThe organization name. The name is not case sensitive. |
Nom, Type, Description | |||
---|---|---|---|
name string ObligatoireThe name of the campaign | |||
description string ObligatoireA description for the campaign | |||
managers array of strings The logins of the users to set as the campaign managers. At this time, only a single manager can be supplied. | |||
team_managers array of strings The slugs of the teams to set as the campaign managers. | |||
ends_at string ObligatoireThe end date and time of the campaign. The date must be in the future. | |||
contact_link string or null The contact link of the campaign. Must be a URI. | |||
code_scanning_alerts array of objects ObligatoireThe code scanning alerts to include in this campaign | |||
Properties of |
Nom, Type, Description |
---|
repository_id integer ObligatoireThe repository id |
alert_numbers array of integers ObligatoireThe alert numbers |
generate_issues
boolean If true, will automatically generate issues for the campaign. The default is false.
Default: false
Codes d’état de la réponse HTTP pour « Create a campaign for an organization »
Code d’état | Description |
---|---|
200 | OK |
400 | Bad Request |
404 | Resource not found |
422 | Unprocessable Entity |
429 | Too Many Requests |
503 | Service unavailable |
Exemples de code pour « Create a campaign for an organization »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com
par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com
.
Exemple de requête
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/campaigns \
-d '{"name":"Critical CodeQL alerts","description":"Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.","managers":["octocat"],"ends_at":"2024-03-14T00:00:00Z","code_scanning_alerts":[{"repository_id":1296269,"alert_numbers":[1,2]}]}'
Response
Status: 200
{
"number": 3,
"created_at": "2024-02-14T12:29:18Z",
"updated_at": "2024-02-14T12:29:18Z",
"name": "Critical CodeQL alert",
"description": "Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.",
"managers": [
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
}
],
"published_at": "2024-02-14T12:29:18Z",
"ends_at": "2024-03-14T12:29:18Z",
"closed_at": null,
"state": "open",
"alert_stats": {
"open_count": 10,
"closed_count": 3,
"in_progress_count": 3
}
}
Get a campaign for an organization
Gets a campaign for an organization.
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint.
Jetons d’accès affinés pour « Get a campaign for an organization »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
- Jetons d’accès utilisateur d’application GitHub
- Jetons d’accès d’installation d’application GitHub
- Jetons d’accès personnel affiné
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Campaigns" organization permissions (read)
Paramètres pour « Get a campaign for an organization »
Nom, Type, Description |
---|
accept string Setting to |
Nom, Type, Description |
---|
org string ObligatoireThe organization name. The name is not case sensitive. |
campaign_number integer ObligatoireThe campaign number. |
Codes d’état de la réponse HTTP pour « Get a campaign for an organization »
Code d’état | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Unprocessable Entity |
503 | Service unavailable |
Exemples de code pour « Get a campaign for an organization »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com
par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com
.
Exemple de requête
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/campaigns/CAMPAIGN_NUMBER
Response
Status: 200
{
"number": 3,
"created_at": "2024-02-14T12:29:18Z",
"updated_at": "2024-02-14T12:29:18Z",
"name": "Critical CodeQL alert",
"description": "Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.",
"managers": [
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
}
],
"published_at": "2024-02-14T12:29:18Z",
"ends_at": "2024-03-14T12:29:18Z",
"closed_at": null,
"state": "open",
"alert_stats": {
"open_count": 10,
"closed_count": 3,
"in_progress_count": 3
}
}
Update a campaign
Updates a campaign in an organization.
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint.
Jetons d’accès affinés pour « Update a campaign »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
- Jetons d’accès utilisateur d’application GitHub
- Jetons d’accès d’installation d’application GitHub
- Jetons d’accès personnel affiné
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Campaigns" organization permissions (write)
Paramètres pour « Update a campaign »
Nom, Type, Description |
---|
accept string Setting to |
Nom, Type, Description |
---|
org string ObligatoireThe organization name. The name is not case sensitive. |
campaign_number integer ObligatoireThe campaign number. |
Nom, Type, Description |
---|
name string The name of the campaign |
description string A description for the campaign |
managers array of strings The logins of the users to set as the campaign managers. At this time, only a single manager can be supplied. |
team_managers array of strings The slugs of the teams to set as the campaign managers. |
ends_at string The end date and time of the campaign, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ. |
contact_link string or null The contact link of the campaign. Must be a URI. |
state string Indicates whether a campaign is open or closed Peut être: |
Codes d’état de la réponse HTTP pour « Update a campaign »
Code d’état | Description |
---|---|
200 | OK |
400 | Bad Request |
404 | Resource not found |
422 | Unprocessable Entity |
503 | Service unavailable |
Exemples de code pour « Update a campaign »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com
par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com
.
Exemple de requête
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/campaigns/CAMPAIGN_NUMBER \
-d '{"name":"Critical CodeQL alerts"}'
Response
Status: 200
{
"number": 3,
"created_at": "2024-02-14T12:29:18Z",
"updated_at": "2024-02-14T12:29:18Z",
"name": "Critical CodeQL alert",
"description": "Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.",
"managers": [
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
}
],
"published_at": "2024-02-14T12:29:18Z",
"ends_at": "2024-03-14T12:29:18Z",
"closed_at": null,
"state": "open",
"alert_stats": {
"open_count": 10,
"closed_count": 3,
"in_progress_count": 3
}
}
Delete a campaign for an organization
Deletes a campaign in an organization.
The authenticated user must be an owner or security manager for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the security_events
scope to use this endpoint.
Jetons d’accès affinés pour « Delete a campaign for an organization »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
- Jetons d’accès utilisateur d’application GitHub
- Jetons d’accès d’installation d’application GitHub
- Jetons d’accès personnel affiné
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Campaigns" organization permissions (write)
Paramètres pour « Delete a campaign for an organization »
Nom, Type, Description |
---|
accept string Setting to |
Nom, Type, Description |
---|
org string ObligatoireThe organization name. The name is not case sensitive. |
campaign_number integer ObligatoireThe campaign number. |
Codes d’état de la réponse HTTP pour « Delete a campaign for an organization »
Code d’état | Description |
---|---|
204 | Deletion successful |
404 | Resource not found |
503 | Service unavailable |
Exemples de code pour « Delete a campaign for an organization »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com
par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com
.
Exemple de requête
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/campaigns/CAMPAIGN_NUMBER
Deletion successful
Status: 204