Add initial docs for Audit Logs (#12554)

* Add docs for Audit Logs

* Update based on PR comments

* Update audit logs terminology

* Fix wording based on PR comments

* Apply suggestions from code review

Co-authored-by: Emilie Franchomme <42777373+FranchommeE@users.noreply.github.com>

Co-authored-by: Emilie Franchomme <42777373+FranchommeE@users.noreply.github.com>
This commit is contained in:
Jeff 2021-03-29 14:08:51 -04:00 committed by GitHub
parent 3dc5416e5b
commit f5ef070776
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 250 additions and 0 deletions

View File

@ -32,6 +32,11 @@ tags:
description: |
The Advanced Image Management API endpoints allow you to manage Docker images across all repositories.
For more information, see [Advanced Image Management dashboard](https://docs.docker.com/docker-hub/image-management/).
- name: Audit Logs
x-displayName: Audit Logs
description: |
The Audit Logs API endpoints allow you to query audit log events across a namespace.
For more information, see [Audit Log](https://docs.docker.com/docker-hub/audit-log/)
definitions:
UsersLoginRequest:
description: User login details
@ -352,6 +357,89 @@ definitions:
items:
type: string
example: latest
protobufAny:
type: object
properties:
type_url:
type: string
value:
type: string
format: byte
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/definitions/protobufAny'
AuditLogAction:
type: object
properties:
name:
type: string
description: Name of audit log action.
description:
type: string
description: Description of audit log action.
label:
type: string
description: Label for audit log action.
description: Audit Log action
AuditLogActions:
type: object
properties:
actions:
type: array
items:
$ref: '#/definitions/AuditLogAction'
description: List of audit log actions.
label:
type: string
description: Grouping label for a particular set of audit log actions.
GetAuditActionsResponse:
type: object
properties:
actions:
type: object
additionalProperties:
$ref: '#/definitions/AuditLogActions'
description: Map of audit log actions.
description: GetAuditActions response.
GetAuditLogsResponse:
type: object
properties:
logs:
type: array
items:
$ref: '#/definitions/AuditLog'
description: List of audit log events.
description: GetAuditLogs response.
AuditLog:
type: object
properties:
account:
type: string
action:
type: string
name:
type: string
actor:
type: string
data:
type: object
additionalProperties:
type: string
timestamp:
type: string
format: date-time
action_description:
type: string
description: Audit log event.
paths:
/v2/users/login:
post:
@ -521,3 +609,165 @@ paths:
description: Forbidden - this API is only available to users on Pro or Team plans
schema:
$ref: '#/definitions/ErrorResponse'
/v2/auditlogs/{account}:
get:
summary: Returns list of audit log events.
description: Get audit log events for a given namespace.
operationId: AuditLogs_GetAuditLogs
responses:
200:
description: A successful response.
schema:
$ref: '#/definitions/GetAuditLogsResponse'
examples:
application/json:
logs:
- account: docker
action: repo.tag.push
name: docker/example
actor: docker
data:
digest: 'sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa'
tag: latest
timestamp: '2021-02-19T01:34:35Z'
action_description: 'pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example'
429:
description: ''
schema: {}
examples:
application/json:
detail: Rate limit exceeded
error: false
500:
description: ''
schema: {}
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/rpcStatus'
parameters:
- name: account
description: Namespace to query audit logs for.
in: path
required: true
type: string
- name: action
description: 'action name one of ["repo.tag.push", ...]. Optional parameter to filter specific audit log actions.'
in: query
required: false
type: string
- name: name
description: 'name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member.'
in: query
required: false
type: string
- name: actor
description: actor name. Optional parameter to filter audit log events to the specific user who triggered the event.
in: query
required: false
type: string
- name: from
description: Start of the time window you wish to query audit events for.
in: query
required: false
type: string
format: date-time
- name: to
description: End of the time window you wish to query audit events for.
in: query
required: false
type: string
format: date-time
- name: page
description: page - specify page number. Page number to get.
in: query
required: false
type: integer
format: int32
default: 1
- name: page_size
description: page_size - specify page size. Number of events to return per page.
in: query
required: false
type: integer
format: int32
default: 25
tags:
- "Audit Logs"
/v2/auditlogs/{account}/actions:
get:
summary: Returns list of audit log actions.
description: Get audit log actions for a namespace to be used as a filter for querying audit events.
operationId: AuditLogs_GetAuditActions
responses:
200:
description: A successful response.
schema:
$ref: '#/definitions/GetAuditActionsResponse'
examples:
application/json:
actions:
org:
actions:
- name: team.create
description: contains team create events
label: Team Created
- name: team.delete
description: contains team delete events
label: Team Deleted
- name: team.member.add
description: contains team member add events
label: Team Member Added
- name: team.member.remove
description: contains team member remove events
label: Team Member Removed
- name: team.member.invite
description: contains team member invite events
label: Team Member Invited
- name: member.removed
description: contains org member remove events
label: Organization Member Removed
- name: create
description: contains organization create events
label: Organization Created
label: Organization
repo:
actions:
- name: create
description: contains repository create events
label: Repository Created
- name: delete
description: contains repository delete events
label: Repository Deleted
- name: change_privacy
description: contains repository privacy change events
label: Privacy Changed
- name: tag.push
description: contains image tag push events
label: Tag Pushed
- name: tag.delete
description: contains image tag delete events
label: Tag Deleted
label: Repository
429:
description: ''
schema: {}
examples:
application/json:
detail: Rate limit exceeded
error: false
500:
description: ''
schema: {}
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/rpcStatus'
parameters:
- name: account
description: Namespace to query audit log actions for.
in: path
required: true
type: string
tags:
- "Audit Logs"