In this demo, we will use in-toto to secure a software supply chain with a very simple workflow. Bob is a developer for a project, Carl packages the software, and Alice oversees the project. So, using in-toto's names for the parties, Alice is the project owner - she creates and signs the software supply chain layout with her private key - and Bob and Carl are project functionaries - they carry out the steps of the software supply chain as defined in the layout.
For the sake of demonstrating in-toto, we will have you run all parts of the software supply chain. This is, you will perform the commands on behalf of Alice, Bob and Carl as well as the client who verifies the final product.
Virtual Environments (optional)
We highly recommend installing in-toto
and its dependencies in a
venv
Python virtual
environment. Just copy-paste the following snippet to create a virtual
environment:
# Create the virtual environment
python -m venv in-toto-demo
# Activate the virtual environment
# This will add the prefix "(in-toto-demo)" to your shell prompt
source in-toto-demo/bin/activate
Get demo files and install in-toto
# Fetch the demo repo using git
git clone https://github.com/in-toto/demo.git
# Change into the demo directory
cd demo
# Install a compatible version of in-toto
pip install -r requirements.txt
Note: If you are having troubles installing in-toto, make sure you have all the system dependencies. See the installation guide on in-toto.readthedocs.io for details.
Inside the demo directory you will find four directories: owner_alice
,
functionary_bob
, functionary_carl
and final_product
. Alice, Bob and Carl
already have RSA keys in each of their directories. This is what you see:
tree # If you don't have tree, try 'find .' instead
# the tree command gives you the following output
# .
# ├── README.md
# ├── final_product
# ├── functionary_bob
# │ ├── bob
# │ └── bob.pub
# ├── functionary_carl
# │ ├── carl
# │ └── carl.pub
# ├── owner_alice
# │ ├── alice
# │ ├── alice.pub
# │ └── create_layout.py
# ├── requirements.txt
# ├── run_demo.py
# └── run_demo_md.py
Note: if you don't want to type or copy & paste commands and would rather watch a script run through the commands, jump to the last section of this document
First, we will need to define the software supply chain layout. To simplify this process, we provide a script that generates a simple layout for the purpose of the demo.
In this software supply chain layout, we have Alice, who is the project
owner that creates the layout, Bob, who clones the project's repo and
performs some pre-packaging editing (update version number), and Carl, who uses
tar
to package the project sources into a tarball, which
together with the in-toto metadata composes the final product that will
eventually be installed and verified by the end user.
# Create and sign the software supply chain layout on behalf of Alice
cd owner_alice
python create_layout.py
The script will create a layout, add Bob's and Carl's public keys (fetched from
their directories), sign it with Alice's private key and dump it to root.layout
.
In root.layout
, you will find that (besides the signature and other information)
there are three steps, clone
, update-version
and package
, that
the functionaries Bob and Carl, identified by their public keys, are authorized
to perform.
Now, we will take the role of the functionary Bob and perform the step
clone
on his behalf, that is we use in-toto to clone the project repo from GitHub and
record metadata for what we do. Execute the following commands to change to Bob's
directory and perform the step.
cd ../functionary_bob
in-toto-run --step-name clone --use-dsse --products demo-project/foo.py --signing-key bob -- git clone https://github.com/in-toto/demo-project.git
Here is what happens behind the scenes:
- In-toto wraps the command
git clone https://github.com/in-toto/demo-project.git
, - hashes the contents of the source code, i.e.
demo-project/foo.py
, - adds the hash together with other information to a metadata file,
- signs the metadata with Bob's private key, and
- stores everything to
clone.[Bob's keyid].link
.
Before Carl packages the source code, Bob will update
a version number hard-coded into foo.py
. He does this using the in-toto-record
command,
which produces the same link metadata file as above but does not require Bob to wrap his action in a single command.
So first Bob records the state of the files he will modify:
# In functionary_bob directory
in-toto-record start --step-name update-version --use-dsse --signing-key bob --materials demo-project/foo.py
Then Bob uses an editor of his choice to update the version number in demo-project/foo.py
, e.g.:
sed -i.bak 's/v0/v1/' demo-project/foo.py && rm demo-project/foo.py.bak
And finally he records the state of files after the modification and produces
a link metadata file called update-version.[Bob's keyid].link
.
# In functionary_bob directory
in-toto-record stop --step-name update-version --use-dsse --signing-key bob --products demo-project/foo.py
Bob has done his work and can send over the sources to Carl, who will create the package for the user.
# Bob has to send the update sources to Carl so that he can package them
cp -r demo-project ../functionary_carl/
Now, we will perform Carl’s package
step by executing the following commands
to change to Carl's directory and create a package of the software project
cd ../functionary_carl
in-toto-run --step-name package --use-dsse --materials demo-project/foo.py --products demo-project.tar.gz --signing-key carl -- tar --exclude ".git" -zcvf demo-project.tar.gz demo-project
This will create another step link metadata file, called package.[Carl's keyid].link
.
It's time to release our software now.
Let's first copy all relevant files into the final_product
that is
our software package demo-project.tar.gz
and the related metadata files root.layout
,
clone.[Bob's keyid].link
, update-version.[Bob's keyid].link
and package.[Carl's keyid].link
:
cd ..
cp owner_alice/root.layout functionary_bob/clone.210dcc50.link functionary_bob/update-version.210dcc50.link functionary_carl/package.be06db20.link functionary_carl/demo-project.tar.gz final_product/
And now run verification on behalf of the client:
cd final_product
# Fetch Alice's public key from a trusted source to verify the layout signature
# Note: The functionary public keys are fetched from the layout
cp ../owner_alice/alice.pub .
in-toto-verify --layout root.layout --verification-keys alice.pub
This command will verify that
- the layout has not expired,
- was signed with Alice’s private key,
and that according to the definitions in the layout - each step was performed and signed by the authorized functionary
- the recorded materials and products follow the artifact rules and
- the inspection
untar
finds what it expects.
From it, you will see the meaningful output PASSING
and a return value
of 0
, that indicates verification worked out well:
echo $?
# should output 0
Now, let’s try to tamper with the software supply chain.
Imagine that someone got a hold of the source code before Carl could package it.
We will simulate this by changing demo-project/foo.py
on Carl's machine
(in functionary_carl
directory) and then let Carl package and ship the
malicious code.
cd ../functionary_carl
echo something evil >> demo-project/foo.py
Carl thought that this is the genuine code he got from Bob and unwittingly packages the tampered version of foo.py
in-toto-run --step-name package --use-dsse --materials demo-project/foo.py --products demo-project.tar.gz --signing-key carl -- tar --exclude ".git" -zcvf demo-project.tar.gz demo-project
and ships everything out as final product to the client:
cd ..
cp owner_alice/root.layout functionary_bob/clone.210dcc50.link functionary_bob/update-version.210dcc50.link functionary_carl/package.be06db20.link functionary_carl/demo-project.tar.gz final_product/
cd final_product
in-toto-verify --layout root.layout --verification-keys alice.pub
This time, in-toto will detect that the product foo.py
from Bob's update-version
step was not used as material in Carl's package
step (the verified hashes
won't match) and therefore will fail verification an return a non-zero value:
echo $?
# should output 1
Congratulations! You have completed the in-toto demo! This exercise shows a very simple case in how in-toto can protect the different steps within the software supply chain. More complex software supply chains that contain more steps can be created in a similar way. You can read more about what in-toto protects against and how to use it on in-toto's Github page.
If you want to run the demo again, you can use the following script to remove all the files you created above.
cd .. # You have to be the demo directory
python run_demo.py -c
The same script can be used to sequentially execute all commands listed above. Just change into the demo
directory, run python run_demo.py
without flags and observe the output.
# In the demo directory
python run_demo.py