= xygeni-goat - Vulnerable repository against supply chain attacks :toc: :toc-title: Contents :toclevels: 1

image:https://img.shields.io/badge/maintained%20by-xygeni.io-blueviolet[Maintained by xygeni.io,link=https://xygeni.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=xygeni-goat]

A deliberately vulnerable repository against software supply chain attacks, by Xygeni.

== Introduction

image:xygeni-goat-logo.png[xygeni-goat,220,,float="right", align="center", title="Created by Mat fine from Noun Project"]

Xygeni-goat helps to understand DevOps teams the best practices to follow and which issues should be avoided, for having a good security posture, lowering the risk against software supply chain attacks. Looking at the elements reported as security flaws, you may learn about misconfigurations to avoid. IaC templates that contains insecure configurations, hardcoded secrets, unsafe tool configurations, troublesome dependencies and more are covered.

This repository is based on existing "Goat" projects, like OWASP https://github.com/WebGoat/WebGoat[WebGoat].

Shear the (nefarious) goat !

WARNING: This repository is for educational purposes only. Do NOT attempt to use the techniques and items shown for unauthorized hacking. Do NOT deploy assets from this repository this in any environment.

DISCLAIMER: Xygeni-goat comes with no warranties. By using xygeni-goat, you take full responsibility for any outcomes. Xygeni would not be liable of any misuse of the information and assets contained in this repository.

== Getting Started

=== Clone the repo, or download

git clone https://github.com/xygeni/xygeni-goat.git

or

gh repo clone xygeni/xygeni-goat

=== Get bearer token

First you will need a bearer (API) token from your Xygeni subscription. Please follow the instructions in link:https://docs.xygeni.io/administration/administration.html#_generate_token_for_scanner[Generate Token for Scanner].

We assume that you set a TOKEN environment variable with the token.

NOTE: We do recommend to use API (bearer) token instead of the (now deprecated) username/password for using Xygeni scanner, although the installation script supports both.

=== Install Xygeni scanner

If you choose to use the Xygeni scanner Docker image, go to next step.

Download the installation script and run it:

Under Linux / macOS (bash):

[source,shell]

Download the install script

curl -sLO https://get.xygeni.io/latest/scanner/install.sh

Check the scanner checksum published in xygeni GitHub repository (a separate environment from cloud),

or better review the install script yourself ;)

echo "$(curl -s https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/install.sh.sha256) install.sh" | sha256sum --check

Under macOS, use shasum -a 256 --check instead if sha256sum is not installed

Run the install script, creating the scanner in your chosen directory

$ ./install.sh -o -t $TOKEN --dir $HOME/my-custom-scanner-dir

Under Windows (PowerShell):

[source,powershell]

Download the install script (via Invoke-WebRequest)

iwr https://get.xygeni.io/latest/scanner/install.ps1 -useb -OutFile install.ps1

Check the scanner checksum published in xygeni GitHub repo,

or better review the install script yourself ;)

(Get-FileHash '.\install.ps1' -Algorithm SHA256).Hash -eq ` (iwr https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/install.ps1.sha256)

Run the install script, creating the scanner in your chosen directory

.\install.ps1 -o -verbose -t "$Env:XYGENI_TOKEN" -dir ~\my-custom-scanner-dir

TIP: You may add a shortcut (using an alias, creating a link to the )

See https://docs.xygeni.io/scanner/install_script.html[Xygeni Scanner Install] for full details.

=== Run the scanner

Run the scan command over the contents in the vulnerable directory, or any subdirectory beneath for a partial analysis. [source,shell]

cd $HOME/my-custom-scanner-dir xygeni scan -n --dir --no-upload

Under Windows (Powershell)

[source,powershell]

cd ~\my-custom-scanner-dir xygeni.cmd scan -n --dir --no-upload

Or, if you prefer to run the https://docs.xygeni.io/integrations/docker/docker.html[Xygeni scanner Docker image]:

[source,shell]

docker compose run xygeni scan -n project_to_scan_name --dir /app --no-upload

== Contributing

You may add your own vulnerable items to help others learn about additional security issues, and raise awareness on new potential attacks. We recommend you to keep the existing directory structure for better categorizing those security issues. Pull Requests are welcomed !

In addition, if you want to add a new "capture the flag" (CTF) check, you are welcome!

=== Development

. Clone the repository: +

git clone https://github.com/xygeni/xygeni-goat.git

+ or +

gh repo clone xygeni/xygeni-goat

+ Alternatively, you may https://docs.github.com/en/get-started/quickstart/fork-a-repo[fork the repo].

. Create your topic branch

. Develop your changes + We recommend to follow the existing directory structure for categorizing the security issue.

. Test your changes + If you developed a new check, test with [TBD]. + If you created a new vulnerable element, test it with Xygeni scanner, as shown in the <<Getting Started,Getting Started>> section.

. Push commits to your topic branch.

. Create a pull request, using gh pr create command or the GitHub desktop / web UI. + After review, your PR will be merged.

=== Add a new Capture The Flag challenge

[TBD]

Each CTF challenge has a separate directory in the ctf directory. Follow the steps below to add a CTF challenge:

. Write challenge description. . Choose category and difficulty level. . Write hints for help. . Add a flag. Ensure that it is not accesible when solving other CTF challenges. . Write tests. . Write the solution. . Create a README.md in your CTF directory.

== Support

[TBD]