Skip to content
/ awscurl Public

curl-like access to AWS resources with AWS Signature Version 4 request signing.

License

Notifications You must be signed in to change notification settings

okigan/awscurl

Repository files navigation

awscurl Donate Donate Donate

PyPI Build Status Docker Hub CI badge

Edit with gitpod Edit with vscode Edit with github codespaces

curl-like tool with AWS Signature Version 4 request signing.

Features

  • performs requests to AWS services with request signing using curl interface
  • supports IAM profile credentials

Overview

Requests to AWS API must be signed (see Signing AWS API Requests) automates the process of signing and makes requests to AWS as simple as a standard curl command.

Installation

pip install awscurl

Installation from source (bleeding edge)

pip install git+https://github.com/okigan/awscurl

Installation via Homebrew for MacOS

brew install awscurl

Running via Docker

docker pull okigan/awscurl # or via docker pull ghcr.io/okigan/awscurl 

or via Github docker registry

docker pull ghcr.io/okigan/awscurl 

then

$ docker run --rm -it okigan/awscurl --access_key ACCESS_KEY  --secret_key SECRET_KEY --service s3 s3://...

# or allow access to local credentials as following
$ docker run --rm -it -v "$HOME/.aws:/root/.aws" okigan/awscurl --service s3 s3://...

To shorten the length of docker commands use the following alias:

alias awscurl='docker run --rm -ti -v "$HOME/.aws:/root/.aws" -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SECURITY_TOKEN -e AWS_PROFILE okigan/awscurl'

This will allow you to run awscurl from within a Docker container as if it was installed on the host system:

awscurl

Examples

  • Call S3: List bucket content

    $ awscurl --service s3 'https://awscurl-sample-bucket.s3.amazonaws.com' | tidy -xml -iq
    <?xml version="1.0" encoding="utf-8"?>
    <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Name>awscurl-sample-bucket</Name>
      <Prefix></Prefix>
      <Marker></Marker>
      <MaxKeys>1000</MaxKeys>
      <IsTruncated>false</IsTruncated>
      <Contents>
        <Key>awscurl-sample-file.txt</Key>
        <LastModified>2017-07-25T21:27:38.000Z</LastModified>
        <ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
        <Size>0</Size>
        <StorageClass>STANDARD</StorageClass>
      </Contents>
    </ListBucketResult>
  • Call EC2:

    $ awscurl --service ec2 'https://ec2.amazonaws.com?Action=DescribeRegions&Version=2013-10-15' | tidy -xml -iq 
    <?xml version="1.0" encoding="utf-8"?>
    <DescribeRegionsResponse xmlns="http://ec2.amazonaws.com/doc/2013-10-15/">
    
      <requestId>96511ccd-2d6d-4d63-ad9b-6be6f2c9874d</requestId>
      <regionInfo>
        <item>
          <regionName>eu-north-1</regionName>
          <regionEndpoint>ec2.eu-north-1.amazonaws.com</regionEndpoint>
        </item>
        <item>
          <regionName>ap-south-1</regionName>
          <regionEndpoint>ec2.ap-south-1.amazonaws.com</regionEndpoint>
        </item>
      </regionInfo>
    </DescribeRegionsResponse>
  • Call API Gateway:

    $ awscurl --service execute-api -X POST -d @request.json \
      https://<prefix>.execute-api.us-east-1.amazonaws.com/<resource>

Options

usage: __main__.py [-h] [-v] [-i] [-X REQUEST] [-d DATA] [-H HEADER] [-k] [--fail-with-body] [--data-binary] [--region REGION] [--profile PROFILE] [--service SERVICE]
                   [--access_key ACCESS_KEY] [--secret_key SECRET_KEY] [--security_token SECURITY_TOKEN] [--session_token SESSION_TOKEN] [-L] [-o <file>]
                   uri

Curl AWS request signing

positional arguments:
  uri

options:
  -h, --help            show this help message and exit
  -v, --verbose         verbose flag (default: False)
  -i, --include         include headers in the output (default: False)
  -X REQUEST, --request REQUEST
                        Specify request command to use (default: GET)
  -d DATA, --data DATA  HTTP POST data (default: )
  -H HEADER, --header HEADER
                        HTTP header (default: None)
  -k, --insecure        Allow insecure server connections when using SSL (default: False)
  --fail-with-body      Fail on HTTP errors but save the body (default: False)
  --data-binary         Process HTTP POST data exactly as specified with no extra processing whatsoever. (default: False)
  --region REGION       AWS region [env var: AWS_DEFAULT_REGION] (default: us-east-1)
  --profile PROFILE     AWS profile [env var: AWS_PROFILE] (default: default)
  --service SERVICE     AWS service (default: execute-api)
  --access_key ACCESS_KEY
                        [env var: AWS_ACCESS_KEY_ID] (default: None)
  --secret_key SECRET_KEY
                        [env var: AWS_SECRET_ACCESS_KEY] (default: None)
  --security_token SECURITY_TOKEN
                        [env var: AWS_SECURITY_TOKEN] (default: None)
  --session_token SESSION_TOKEN
                        [env var: AWS_SESSION_TOKEN] (default: None)
  -L, --location        Follow redirects (default: False)
  -o <file>, --output <file>
                        Write to file instead of stdout (default: )

 In general, command-line values override environment variables which override defaults.

If you do not specify the --access_key or --secret_key (or environment variables), awscurl will attempt to use the credentials you set in ~/.aws/credentials. If you do not specify a --profile or AWS_PROFILE, awscurl uses default.

Who uses awscurl

Star History

Star History Chart

Related projects

Last but not least