Remote Sources
There are a number of options for formatting the URL provided to the
source
attribute on policy
and import "module"
blocks. This flexibility
should solve most use cases and allow for reusable policies and modules.
Supported Protocols
NOTE: All protocols are supported on the CLI, however each production Sentinel integration may not. Be sure to read the appropriate integration documentation to check the supported protocols.
- Local filesystem
- Git
- Mercurial
- HTTP
- Amazon S3
- Google GCP
Forced Protocols
Due to the ambiguous nature of URLs, it is possible to force a particular protocol to be used during the fetch. To achieve this, simply prefix the url with the appropriate protocol as listed below:
Example:
The above would download the provided HTTP URL using the Git protocol.
Protocol Options
In addition to some global options, there are options available to specific protocols to perform features such as authentication.
Subdirectories / File Pathing
When supplying URLs that point to a directory (eg. git
), a subdirectory and
file can be provided by suffixing the URL with //
and the path. For example,
if we have a git repository that has a policy, main.sentinel
in the root, we
could directly fetch the file by using the following:
Or, if the file was nested in the policies
folder:
Checksumming
For downloads of any protocol, you can automatically verify a checksum. To
checksum a file, append a checksum
query parameter to the URL. The parameter
value can be in the format of type:value or just value, where type is "md5",
"sha1", "sha256", "sha512" or "file" . The "value" should be the actual
checksum value or download URL for "file". When type part is omitted, type will
be guessed based on the length of the checksum string.
Unarchiving
An archive
query parameter can be supplied to explicitly state what format
to attempt to extract, if required. The supported formats are:
If a URL has an extension that matches one of the supported formats, it will use that format to unarchive.
The above would use the zip
format to unarchive.
Would force the zip
format. If for some reason you required archiving to be
disabled, this can also be achieved by using the false
value.
Git (git
)
ref
- The Git ref to checkout. This is a ref, so it can point to a commit SHA, a branch name, etc. If it is a named ref such as a branch name, it will be updated to the latest on each get.sshkey
- An SSH private key to use during clones. The provided key must be a base64-encoded string. For example, to generate a suitable sshkey from a private key file on disk, you would run base64 -w0 \<file>. Note: Git 2.3+ is required to use this feature.depth
- The Git clone depth. The provided number specifies the lastn
revisions to clone from the repository.
The git getter accepts both URL-style SSH addresses like
git::ssh://git@example.com/foo/bar
, and "scp-style" addresses like
git::git@example.com/foo/bar
. In the latter case, omitting the git::
forced
prefix is allowed if the username prefix is exactly git@.
The "scp-style" addresses cannot be used in conjunction with the ssh://
scheme prefix, because in that case the colon is used to mark an optional port
number to connect on, rather than to delimit the path from the host.
Mercurial (hg
)
rev
- The Mercurial revision to checkout.
HTTP (http
or https
)
Basic Authentication
To use HTTP basic authentication, simply prepend username:password@
to the
hostname in the URL such as https://Aladdin:OpenSesame@www.example.com/index.html
.
All special characters, including the username and password, must be URL
encoded.
S3 (s3
)
The following query parameters are available and will take priority when authenticating against an S3 bucket.
aws_access_key_id
- AWS access key.aws_access_key_secret
- AWS access key secret.aws_access_token
- AWS access token if this is being used.aws_profile
- Use this profile from local ~/.aws/ config. Takes priority over the other three.