Legal holds and AWS Backup

Legal hold overview

A legal hold is an administrative tool that helps prevent backups from being deleted while under a hold. While the hold is in place, backups under a hold cannot be deleted and lifecycle policies that would alter the backup status (such as transition to a Deleted state) are delayed until the legal hold is removed.

Legal holds can be applied to one or more backups (also known as recovery points) created by AWS Backup if their lifecycles allow it. A type of backup called a continuous backup has a maximum lifecycle of 35 days. Legal holds do not extend a continuous backup lifecycle.

When a legal hold is created, it can take into account specific filtering criteria, such as resource types and resource IDs. Additionally, you can define the creation date range of backups you wish to include in a legal hold.

Legal holds apply only to the original backup on which they are placed. When a backup is copied across Regions or accounts (if the resource supports it), it does not retain or carry its legal hold with it. A legal hold, like other resources, has a unique ARN (Amazon Resource Name) associated with it. Only recovery points created by AWS Backup can be part of a legal hold.

Note that while AWS Backup Vault Lock provides additional protections and immutability to a vault, a legal hold provides additional protection against deletion of individual backups (recovery points). The legal hold does not expire and retains the data within the backup indefinitely. The hold remains active until it is released by a user with sufficient permissions.

Multiple legal holds

A backup can have more than one legal hold. Legal holds and backups have a many:many relationship, meaning a backup can have more than legal hold and a legal hold can include more than one backup.

A backup cannot be deleted as long as it has at least one legal hold. Once all legal holds on a backup are removed, it is subject to its retention lifecycle properties. Maintain at least one legal hold to prevent backup deletion. Legal holds can be applied to a recovery point retained past its backup lifecycle retention date (due to an existing legal hold).

Each account can have a maximum of 50 legal holds active at one time.

Create a legal hold

A legal hold can added to an existing backup (recovery point).

Backups (recovery points) with a status of EXPIRED or DELETING will not be included in the legal hold. Recovery points (backups) with the status of CREATING may not be included in the legal hold, depending on the time of completion.

Legal holds can be added by users who have the required IAM permissions.

aws backup create-legal-hold --title "my title" \
    --description "my description" \
    --recovery-point-selection "VaultNames=string,DateRange={FromDate=timestamp,ToDate=timestamp}"

View legal holds

You can see legal hold details in the AWS Backup console or programmatically.

GET /legal-holds/{legalHoldId} HTTP/1.1

Request

empty body

Response

{
    Title: string,
    Status: LegalHoldStatus, 
    Description: string, // 280 chars max
    CancelDescription: string, // this is provided during cancel // 280 chars max
    LegalHoldId: string,
    LegalHoldArn: string,
    CreatedTime: number,
    CanceledTime: number,
    
   ResourceSelection: {
        VaultArns: [ string ]
        Resources: [ string ]
   }, 
   ResourceFilters: {
        DateRange: {
          FromDate: number,
          ToDate: number
        }
   }
}

GET /legal-holds/
  &maxResults=MaxResults
  &nextToken=NextToken


Request

empty body
url params: 
  MaxResults: number  // optional,
  NextToken: string  // optional

status: Valid values: CREATING | ACTIVE | CANCELED | CANCELING
maxResults: 1-1000



Response

{
  NextToken: token,
  LegalHolds: [
    Title: string,
    Status: string, 
    Description: string, // 280 chars max
    CancelDescription: string, // this is provided during cancel // 280 chars max
    LegalHoldId: string,
    LegalHoldArn: string,
    CreatedTime: number,
    CanceledTime: number,
  ]

}

The following are the possible status values.

Release a legal hold

Legal holds remain in effect until they are removed by a user with sufficient permissions. Removing a legal hold is also known as cancelling, deleting, or releasing a legal hold. Removing a legal hold eliminates it from all backups to which it was attached. Any backups that expired during the legal hold are deleted within 24 hours after the legal hold is removed.

DELETE /legal-holds/{legalHoldId}


Request

{
   CancelDescription: String
   DeleteAfterDays: number // optional
}


DeleteAfterDays: optional. 
  Defaults to 180 days. how long to keep legal hold record after canceled.
  This applies to the actual legal hold record only.
  Recovery points are unlocked as soon as cancelation processes and are not subject to this date.

Response 

Empty body

200 if successful
other standard codes