Skip to content

Commit

Permalink
updated help docs in code and readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@scrthq
scrthq committed Oct 30, 2024
1 parent 450311f commit 7072698
Show file tree
Hide file tree
Showing 4 changed files with 82 additions and 45 deletions.
4 changes: 2 additions & 2 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -183,8 +183,8 @@ FROM core as ci
ENV ASH_TARGET=ci


# Final stage: Local development final version. This image contains all dependencies
# for ASH, but ensures it is launched as a non-root user for local runs.
# Final stage: Non-root user final version. This image contains all dependencies
# for ASH from the `core` stage, but ensures it is launched as a non-root user.
# Running as a non-root user impacts the ability to run ASH reliably across CI
# platforms and other orchestrators where the initialization and launch of the image
# is not configurable for customizing the running UID/GID.
Expand Down
50 changes: 32 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -208,25 +208,39 @@ ash --source-dir . --ext py

```text
NAME:
ash
ash
SYNOPSIS:
ash [OPTIONS] --source-dir /path/to/dir --output-dir /path/to/dir
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.
--offline Build ASH for offline execution. Defaults to false.
--offline-semgrep-rulesets Specify Semgrep rulesets for use in ASH offline mode. Defaults to 'p/ci'.
--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.
--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)
--format Output format of the aggregated_results file segments.
Options: text, json
Default: text
--target Specify the target stage of the ASH image to build.
Options: non-root, ci
Default: non-root
--offline Build ASH for offline execution. Defaults to false.
--offline-semgrep-rulesets Specify Semgrep rulesets for use in ASH offline mode.
Default: p/ci
--no-cleanup Don't cleanup the work directory where temp reports are stored during scans.
--ext | -extension Force a file extension to scan. Defaults to identify files automatically.
-d | --debug Print ASH debug log information where applicable.
-q | --quiet Don't print verbose text about the build process.
-v | --version Prints version number.
-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.
-p | --preserve-report Add timestamp to the final report file to avoid overwriting it after multiple executions.
INFO:
For more information, please visit https://github.com/awslabs/automated-security-helper
```

## FAQ
Expand Down Expand Up @@ -260,7 +274,7 @@ OPTIONS:

- Q: How to run `ash` in an environment without internet connectivity/with an airgap?

A: From your environment which does have internet connectivity, build the ASH image using `--offline` and `--offline-semgrep-rulesets` to specify what resources to package into the image. Environment variable `$ASH_IMAGE_NAME` controls the name of the image. After building, push to your container repository of choice which will be available within the airgapped environment. When you go to execute ASH in your offline environment, passing `--no-build` to `ash` alongside `--offline` and `--offline-semgrep-rulesets` will use your offline image and skip the build. Specify `$ASH_IMAGE_NAME` to override ASH's container image to the previously-built image available within your airgapped environment.
A: From your environment which does have internet connectivity, build the ASH image using `--offline` and `--offline-semgrep-rulesets` to specify what resources to package into the image. Environment variable `$ASH_IMAGE_NAME` controls the name of the image. After building, push to your container repository of choice which will be available within the airgapped environment. When you go to execute ASH in your offline environment, passing `--no-build` to `ash` alongside `--offline` and `--offline-semgrep-rulesets` will use your offline image and skip the build. Specify `$ASH_IMAGE_NAME` to override ASH's container image to the previously-built image available within your airgapped environment.

## Feedback

Expand Down
15 changes: 11 additions & 4 deletions ash
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
# Resolve the absolute path of the parent of the script directory (ASH repo root)
export ASH_ROOT_DIR="$(cd "$(dirname "$0")"; pwd)"
export ASH_UTILS_DIR="${ASH_ROOT_DIR}/utils"
export ASH_IMAGE_NAME=${ASH_IMAGE_NAME:-"automated-security-helper:local"}

# Set local variables
SOURCE_DIR=""
Expand All @@ -22,6 +21,7 @@ NO_RUN="NO"
DEBUG="NO"
OFFLINE="NO"
OFFLINE_SEMGREP_RULESETS="p/ci"
TARGET_STAGE="non-root"
# Parse arguments
while (("$#")); do
case $1 in
Expand Down Expand Up @@ -69,13 +69,17 @@ while (("$#")); do
--no-run)
NO_RUN="YES"
;;
--debug)
--debug|-d)
DEBUG="YES"
;;
--format)
shift
OUTPUT_FORMAT="$1"
;;
--target)
shift
TARGET_STAGE="$1"
;;
--help | -h)
source "${ASH_ROOT_DIR}/ash-multi" --help
exit 0
Expand All @@ -95,6 +99,8 @@ while (("$#")); do
shift
done

export ASH_IMAGE_NAME=${ASH_IMAGE_NAME:-"automated-security-helper:${TARGET_STAGE}"}

# Default to the pwd
if [ "${SOURCE_DIR}" = "" ]; then
SOURCE_DIR="$(pwd)"
Expand Down Expand Up @@ -138,19 +144,20 @@ else
CONTAINER_GID_OPTION=""
if [[ ${CONTAINER_UID_SPECIFIED} = "YES" ]]; then
CONTAINER_UID_OPTION="--build-arg UID=${CONTAINER_UID}" # set the UID build-arg if --container-uid is specified
else
elif [[ "${HOST_UID}" != "" ]]; then
CONTAINER_UID_OPTION="--build-arg UID=${HOST_UID}" # set the UID build-arg to the caller's UID if --container-uid is not specified
fi
if [[ ${CONTAINER_GID_SPECIFIED} = "YES" ]]; then
CONTAINER_GID_OPTION="--build-arg GID=${CONTAINER_GID}" # set the GID build-arg if --container-gid is specified
else
elif [[ "${HOST_GID}" != "" ]]; then
CONTAINER_GID_OPTION="--build-arg GID=${HOST_GID}" # set the GID build-arg to the caller's GID if --container-uid is not specified
fi
echo "Building image ${ASH_IMAGE_NAME} -- this may take a few minutes during the first build..."
${RESOLVED_OCI_RUNNER} build \
${CONTAINER_UID_OPTION} \
${CONTAINER_GID_OPTION} \
--tag ${ASH_IMAGE_NAME} \
--target ${TARGET_STAGE} \
--file "${ASH_ROOT_DIR}/Dockerfile" \
--build-arg OFFLINE="${OFFLINE}" \
--build-arg OFFLINE_SEMGREP_RULESETS="${OFFLINE_SEMGREP_RULESETS}" \
Expand Down
58 changes: 37 additions & 21 deletions ash-multi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,27 +49,43 @@ version_check() {
}

print_usage() {
echo "NAME:"
echo -e "\t$(basename $0)"
echo "SYNOPSIS:"
echo -e "\t$(basename $0) [OPTIONS] --source-dir /path/to/dir --output-dir /path/to/dir"
echo "OPTIONS:"
echo -e "\t-v | --version Prints version number.\n"
echo -e "\t-p | --preserve-report Add timestamp to the final report file to avoid overwriting it after multiple executions."
echo -e "\t--source-dir Path to the directory containing the code/files you wish to scan. Defaults to \$(pwd)"
echo -e "\t--output-dir Path to the directory that will contain the report of the scans. Defaults to \$(pwd)"
echo -e "\t--format Output format of the aggregated_results file segments. Defaults to text. Use json instead to enable parseable output."
echo -e "\t--ext | -extension Force a file extension to scan. Defaults to identify files automatically."
echo -e "\t--offline Build ASH for offline execution. Defaults to false."
echo -e "\t--offline-semgrep-rulesets Specify Semgrep rulesets for use in ASH offline mode. Defaults to 'p/ci'."
echo -e "\t--force Rebuild the Docker images of the scanning tools, to make sure software is up-to-date."
echo -e "\t--no-cleanup Don't cleanup the work directory where temp reports are stored during scans."
echo -e "\t--debug Print ASH debug log information where applicable."
echo -e "\t-q | --quiet Don't print verbose text about the build process."
echo -e "\t-c | --no-color Don't print colorized output."
echo -e "\t-s | --single-process Run ash scanners serially rather than as separate, parallel sub-processes."
echo -e "\t-o | --oci-runner Use the specified OCI runner instead of docker to run the containerized tools.\n"
echo -e "For more information please visit https://github.com/awslabs/automated-security-helper"
local cmd=$(basename "$0")
cat <<-EOF
NAME:
${cmd}
SYNOPSIS:
${cmd} [OPTIONS] --source-dir /path/to/dir --output-dir /path/to/dir
OPTIONS:
--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)
--format Output format of the aggregated_results file segments.
Options: text, json
Default: text
--target Specify the target stage of the ASH image to build.
Options: non-root, ci
Default: non-root
--offline Build ASH for offline execution. Defaults to false.
--offline-semgrep-rulesets Specify Semgrep rulesets for use in ASH offline mode.
Default: p/ci
--no-cleanup Don't cleanup the work directory where temp reports are stored during scans.
--ext | -extension Force a file extension to scan. Defaults to identify files automatically.
-d | --debug Print ASH debug log information where applicable.
-q | --quiet Don't print verbose text about the build process.
-v | --version Prints version number.
-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.
-p | --preserve-report Add timestamp to the final report file to avoid overwriting it after multiple executions.
INFO:
For more information, please visit https://github.com/awslabs/automated-security-helper
EOF
}

# Find all files in the source directory. Method to list the files will be different if the source is a git repository or not
Expand Down

0 comments on commit 7072698

Please sign in to comment.