{"id":13757399,"url":"https://github.com/RhinoSecurityLabs/dsnap","last_synced_at":"2025-05-10T05:32:03.346Z","repository":{"id":48629931,"uuid":"335227182","full_name":"RhinoSecurityLabs/dsnap","owner":"RhinoSecurityLabs","description":"Utility for downloading and mounting EBS snapshots using the EBS Direct API's","archived":false,"fork":false,"pushed_at":"2025-03-17T18:10:30.000Z","size":3416,"stargazers_count":83,"open_issues_count":8,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-09T11:09:23.039Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RhinoSecurityLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-02-02T08:59:26.000Z","updated_at":"2025-04-04T14:04:57.000Z","dependencies_parsed_at":"2024-01-17T16:08:20.297Z","dependency_job_id":"1edc7d27-0c48-4fa2-8d51-1413a650b6c4","html_url":"https://github.com/RhinoSecurityLabs/dsnap","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhinoSecurityLabs%2Fdsnap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhinoSecurityLabs%2Fdsnap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhinoSecurityLabs%2Fdsnap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RhinoSecurityLabs%2Fdsnap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RhinoSecurityLabs","download_url":"https://codeload.github.com/RhinoSecurityLabs/dsnap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253371075,"owners_count":21897998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T12:00:36.523Z","updated_at":"2025-05-10T05:32:03.016Z","avatar_url":"https://github.com/RhinoSecurityLabs.png","language":"Python","funding_links":[],"categories":["Other Awesome Lists"],"sub_categories":["General Utilities"],"readme":"![Python package](https://github.com/RhinoSecurityLabs/dsnap/workflows/Python%20package/badge.svg?branch=main)\n\n# dsnap\n\nUtility for downloading EBS snapshots using the EBS Direct API's.\n\n* Blog Post: [Downloading and Exploring AWS EBS Snapshots](https://rhinosecuritylabs.com/aws/exploring-aws-ebs-snapshots/).\n* This is used as a library by the [Pacu](https://github.com/RhinoSecurityLabs/pacu) module [ebs__download_snapshots](https://github.com/RhinoSecurityLabs/pacu/wiki/Module-Details#ebs__download_snapshots).\n  * Check out the [Pacu integration](#pacu-integration) section to get an idea of the tradeoff's between the using this vs the Pacu module.\n\n#### Recording\n\n![Alt Text](./docs/demo.gif)\n\n## Install\n\n### PyPi\n\n```shell\n% pip install -U pip\n% pip install 'dsnap[cli]'\n```\n\n## Command Reference\n\n```shell\n% dsnap --help\nUsage: dsnap [OPTIONS] COMMAND [ARGS]...\n\n  A utility for managing snapshots via the EBS Direct API.\n\nOptions:\n  --region REGION                 Sets the AWS region.  [default: us-east-1]\n  --profile PROFILE               Shared credential profile to use.\n  --install-completion [bash|zsh|fish|powershell|pwsh]\n                                  Install completion for the specified shell.\n  --show-completion [bash|zsh|fish|powershell|pwsh]\n                                  Show completion for the specified shell, to\n                                  copy it or customize the installation.\n\n  --help                          Show this message and exit.\n\nCommands:\n  create  Create a snapshot for the given instances default device volume.\n  delete  Delete a given snapshot.\n  get     Download a snapshot for a given instance or snapshot ID.\n  init    Write out a Vagrantfile template to explore downloaded snapshots.\n  list    List snapshots in AWS.\n```\n\n## IAM Permissions\n\nNot all these permissions are strictly necessary, for example if you provide an existing snapshot ID with the `get `\ncommand you'll only need `ebs:ListSnapshotBlocks` and `ebs:GetSnapshotBlock`. The rest of the permissions are either\nused to find volumes and snapshots based on instance ID's, create temporary snapshots if none exist or for use with the\n`create` and `delete` commands.\n\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"ebs:ListSnapshotBlocks\",\n                \"ebs:GetSnapshotBlock\",\n                \"ec2:DescribeSnapshots\",\n                \"ec2:DescribeInstances\",\n                \"ec2:DescribeVolumes\",\n                \"ec2:DeleteSnapshot\",\n                \"ec2:CreateSnapshot\",\n                \"ec2:CreateTags\"\n            ],\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\n## Examples\n\n### Listing Snapshots\n```shell\n% dsnap list\n           Id          |   Owner ID   |   State\nsnap-0dbb0347f47e38b96   922105094392   completed\n```\n\n### Downloading a Snapshot\n```shell\n% dsnap get snap-0dbb0347f47e38b96\nOutput Path: /cwd/snap-0dbb0347f47e38b96.img\n```\n\nIf you don't specify a snapshot  you'll get a prompt to ask which one you want to download:\n```shell\n% dsnap get\n0) i-01f0841393cd39f06 (ip-172-31-27-0.ec2.internal, vpc-04a91864355539a41, subnet-0e56cd55282fa9158)\nSelect Instance: 0\n0) vol-0a1aab48b0bc3039d (/dev/sdb)\n1) vol-0c616d718ab00e70c (/dev/xvda)\nSelect Volume: 0\nNo snapshots found, create one? [y/N]: y\nCreating snapshot for Instance(s): i-01f0841393cd39f06 /dev/sdb, Volume: vol-0a1aab48b0bc3039d\nWaiting for snapshot to complete.\nOutput Path: /cwd/snap-0dbb0347f47e38b96.img\nCleaning up snapshot: snap-0543a8681adce0086\n```\n\n### Mounting in Vagrant\nNote: Vagrant does not offer any guarantee's of seperation between the guest and the host. It shouldn't considered a security boundry like most VM's.\n\nThis requires virtualbox to be installed. dsnap init will write a Vagrantfile to the current directory that can be used to mount a specific downloaded snapshot. Conversion to a VDI disk is handled in the Vagrantfile, it will look for the disk file specified in the IMAGE environment variable, convert it to a VDI using `VBoxManage convertdd`. The resulting VDI is destroyed when the Vagrant box is, however the original raw .img file will remain and can be reused as needed.\n\n```shell\n% dsnap init\n% IMAGE=snap-0543a8681adce0086.img vagrant up\n% vagrant ssh\n```\n\n### Mounting With Docker\n\nThis uses libguestfs to work directly with the downloaded img file.\n\n#### Build Docker Container\n```shell\n% git clone https://github.com/RhinoSecurityLabs/dsnap.git\n% cd dsnap\n% make docker/build\n```\n\n#### Run Guestfish Shell\n\n```shell\n% IMAGE=snap-0dbb0347f47e38b96.img make docker/run\n```\n\nThis will take a second to start up. After it drops you into the shell you should be able to run commands like ls, cd, cat. However worth noting they don't always behave exactly like they do in a normal shell.\n\nThe output will give you the basics of how to use the guestfish shell. For a full list of command you can run `help --list`.\n\nBelow is an example of starting the shell and printing the contents of /etc/os-release.\n\n```shell\n% IMAGE=snap-0dbb0347f47e38b96.img make docker/run\ndocker run -it -v \"/cwd/dsnap/snap-0dbb0347f47e38b96.img:/disks/snap-0dbb0347f47e38b96.img\" -w /disks mount --ro -a \"snap-0dbb0347f47e38b96.img\" -m /dev/sda1:/\n\nWelcome to guestfish, the guest filesystem shell for\nediting virtual machine filesystems and disk images.\n\nType: ‘help’ for help on commands\n      ‘man’ to read the manual\n      ‘quit’ to quit the shell\n\n\u003e\u003cfs\u003e cat /etc/os-release\nNAME=\"Amazon Linux\"\nVERSION=\"2\"\nID=\"amzn\"\nID_LIKE=\"centos rhel fedora\"\nVERSION_ID=\"2\"\nPRETTY_NAME=\"Amazon Linux 2\"\nANSI_COLOR=\"0;33\"\nCPE_NAME=\"cpe:2.3:o:amazon:amazon_linux:2\"\nHOME_URL=\"https://amazonlinux.com/\"\n```\n\n## As a Library\n\ndsnap is also meant to be used as a library, however for this purpose it is worth keeping in mind this is an early version and it is still being developed. The interfaces will likely change as new functionality is added.\n\nWe'll do our best to make sure we follow SemVer versioning to avoid any breaking changes in minor and patch versions.\n\n## Related tools\n\n### Pacu Integration\n\nThis project is used by [Pacu](https://github.com/RhinoSecurityLabs/pacu) in the\n[ebs__download_snapshots](https://github.com/RhinoSecurityLabs/pacu/wiki/Module-Details#ebs__download_snapshots) module.\nThe primary benefit of using the Pacu module is to reduce unnecessary API call's, as a tradeoff it doesn't have some\nniceties that are included with dsnap.\n\nFor example the Pacu module reuses snapshots gathered from [ebs__enum_volumes_snapshots](https://github.com/RhinoSecurityLabs/pacu/wiki/Module-Details#ebs__enum_volumes_snapshots), this prevents looking up snapshots more often then needed. At the moment it does not support some dsnap features like creating temporary snapshots or searching for snapshots by instance ID, this however may change in the future.\n\n### Other Interesting Tools\n\nPlease keep in mind that we can't vouch for the following tools. However, we felt they were worth mentioning here.\n\n* [ebs-direct-sec-tools](https://github.com/crypsisgroup/ebs-direct-sec-tools)\n  * In particular the [scansecrets](https://github.com/crypsisgroup/ebs-direct-sec-tools#scansecrets) and [diffsecrets](https://github.com/crypsisgroup/ebs-direct-sec-tools#diffsecrets) commands are interesting because instead of mounting the snapshots they scan the raw image for secrets directly.\n\n\n\n## Development\n\nFor CLI development make sure you include the `cli` extra shown below. You'll also want to invoke the package by using python's `-m` (shown below) for testing local changes, the dnsap binary installed to the environment will only update when you run pip install.\n\n### Setup\n```shell\n% git clone https://github.com/RhinoSecurityLabs/dsnap.git\n% cd dsnap\n% python3 -m venv venv\n% . venv/bin/activate\n% python -m pip install '.[cli]'\n```\n\n### Running With Local Changes\n```shell\n% python -m dsnap --help\n```\n\n### Linting and Type Checking\n```shell\n% make lint\n```\n\n### Testing\n```shell\n% make test\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRhinoSecurityLabs%2Fdsnap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRhinoSecurityLabs%2Fdsnap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRhinoSecurityLabs%2Fdsnap/lists"}