ash
with pre-commit
The security helper tool was created to help you reduce the probability of a security violation in a new code, infrastructure or IAM configuration by providing a fast and easy tool to conduct preliminary security check as early as possible within your development process.
The security helper supports the following vectors:
To start using ash
please make sure to install and configure the following:
Clone the git repository into a folder. For example:
# Set up some variables
REPO_DIR="${HOME}"/Documents/repos/reference
REPO_NAME=automated-security-helper
# Create a folder to hold reference git repositories
mkdir -p ${REPO_DIR}
# Clone the repository into the reference area
git clone https://github.com/awslabs/automated-security-helper "${REPO_DIR}/${REPO_NAME}"
# Set the repo path in your shell for easier access
#
# Add this (and the variable settings above) to
# your ~/.bashrc, ~/.bash_profile, ~/.zshrc, or similar
# start-up scripts so that the ash tool is in your PATH
# after re-starting or starting a new shell.
#
export PATH="${PATH}:${REPO_DIR}/${REPO_NAME}"
# Execute the ash tool
ash --version
ASH uses containers, bash
shell scripts, and multiple background processes running in parallel to run the multiple
source code security scanning tools that it uses. Because of this, running ash
from either a PowerShell
or cmd
shell on Windows is not possible. Furthermore, due to reliance on running containers, usually with Docker Desktop
when running on Windows, there is an implicit dependency on having installed, configured, and operational a
Windows Subsystem for Linux (WSL) 2 environment on the Windows machine where ash
will be run.
To use ash
on Windows:
git
client in the WSL 2 environment. This should be pre-installed, but you may need to update the version
using the apt-get update
command.Once the WSL2 command-line window is open, follow the steps above in Getting Started - Linux or MacOS
to install and run ash
in WSL 2 on the Windows machine.
To run ash
, open a Windows Terminal shell into the WSL 2 environment and use that command-line shell to run the ash
command.
Note: when working this way, be sure to git clone
any git repositories to be scanned into the WSL 2 filesystem.
Results are un-predictable if repositories or file sub-trees in the Windows filesystem are scanned using ash
that is running in the WSL 2 environment.
Tip: If you are using Microsoft VSCode for development, it is possible to configure a "remote" connection using VSCode into the WSL2 environment. By doing this, you can host your git repositories in WSL 2 and still work with them as you have in the past when they were in the Windows filesystem of your Windows machine.
Follow the instruction in the quickstart page to deploy an AWS Cloud9 Environment with ASH pre-installed.
ash
with pre-commit
The ash
tool can be used interactively on a workstation or run using the pre-commit
command.
If pre-commit
is used to run ash
, then the pre-commit
processing takes care of installing
a copy of the ash
git repository and setting up to run the ash
program from that installed
repository. Using pre-commit
still requires usage of WSL 2 when running on Windows.
Using ash
as a pre-commit
hook enables development teams to use the ash
tool
in two ways. First, developers can use ash
as a part of their local development process on whatever
development workstation or environment they are using. Second, ash
can be run in a build automation stage
by running pre-commit run --hook-stage manual ash
in build automation stage.
When using pre-commit
, run the pre-commit
commands while in a folder/directory within the git repository that is
configured with pre-commit
hooks.
Refer to the pre-commit-hooks file for information about the pre-commit
hook itself.
To configure a git repository to use the ash
hook, start with the following pre-commit-config
configuration:
- repo: git@github.com:awslabs/automated-security-helper.git
rev: '1.1.0-e-01Dec2023' # update with the latest tagged version in the repository
hooks:
- id: ash
name: scan files using ash
stages: [ manual ]
# uncomment the line below if using "finch" on MacOS
# args: [ "-f" ]
Once the .pre-commit-hooks.yaml
file is updated, the ash
tool can be run using the following command:
pre-commit run --hook-stage manual ash
Results from the run of the ash
tool can be found in the aggregated_results.txt
file
the --output-dir
folder/directory.
When ASH converts CloudFormation files into CDK and runs cdk-nag on them,
the output of the cdk-nag check results are preserved in a 'ash_cf2cdk_output'
folder/directory under --output-dir
after the ASH scan is run. This folder/directory is
in addition to the aggregated_results.txt
file found in --output-dir
.
# Getting help
ash -h
# Scan a directory
ash --source-dir /my/remote/files
# Save the final report to a different directory
ash --output-dir /my/remote/files
# Force rebuild the entire framework to obtain latests changes and up-to-date database
ash --force
# Force run scan for Python code
ash --source-dir . --ext py
* All commands can be used together.
NAME:
ash
SYNOPSIS:
ash [OPTIONS] --source-dir /path/to/dir --output-dir /path/to/dir
OPTIONS:
-v | --version Prints version number.
-p | --preserve-report Add timestamp to the final report file to avoid overwriting it after multiple executions.
--source-dir Path to the directory containing the code/files you wish to scan. Defaults to $(pwd)
--output-dir Path to the directory that will contain the report of the scans. Defaults to $(pwd)
--ext | -extension Force a file extension to scan. Defaults to identify files automatically.
--force Rebuild the Docker images of the scanning tools, to make sure software is up-to-date.
--no-cleanup Don't cleanup the work directory where temp reports are stored during scans.
--debug Print ASH debug log information where applicable.
-q | --quiet Don't print verbose text about the build process.
-c | --no-color Don't print colorized output.
-s | --single-process Run ash scanners serially rather than as separate, parallel sub-processes.
-o | --oci-runner Use the specified OCI runner instead of docker to run the containerized tools.
Q: How to run ash
on a Windows machine
A: ASH on a windows machine
Q: How to run ash
in a Continuous Integration/Continuous Deployment (CI/CD) pipline?
A: Check the ASH Pipeline solution
Q: How to run ash
with finch
or another Open Container Initiative (OCI) compatible tool.
A: You can configure the OCI compatible tool to use with by using the environment variable ASH_OCI_RUNNER
Q: How to exclude files from scanning.
A: ash
will scan all the files in the folder specified in --source-dir
, or the current directory if invoked without parameters. If the folder is a git repository,
then ash
will use the exclusions in your .gitignore
configuration file. If you want to exclude any specific folder, it must be added to your git ignore list before invoking ash
.
Q: ash
reports there are not files to scan or you see a message stating warning: You appear to have cloned an empty repository.
A: Ensure you're running ASH inside the folder you intend to scan or using the --source-dir
parameter. If the folder where the files reside is part of a git repository, ensure the files are added (committed) before running ASH.
Create an issue here.
See CONTRIBUTING for information on how to contribute to this project.
See CONTRIBUTING for more information.
This library is licensed under the Apache 2.0 License. See the LICENSE file.