Debian Codegraph @

PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: in-toto
3 Version: 2.0.0
4 Summary: A framework to define and secure the integrity of software supply chains
5 Project-URL: Bug Reports, https://github.com/in-toto/in-toto/issues
6 Project-URL: Homepage, https://in-toto.io
7 Project-URL: Source, https://github.com/in-toto/in-toto
8 Author-email: "New York University: Secure Systems Lab" <[email protected]>
9 License-Expression: Apache-2.0
10 License-File: LICENSE
11 Keywords: security,software,supply chain
12 Classifier: Development Status :: 5 - Production/Stable
13 Classifier: Intended Audience :: Developers
14 Classifier: License :: OSI Approved :: Apache Software License
15 Classifier: Natural Language :: English
16 Classifier: Operating System :: MacOS :: MacOS X
17 Classifier: Operating System :: POSIX
18 Classifier: Operating System :: POSIX :: Linux
19 Classifier: Programming Language :: Python
20 Classifier: Programming Language :: Python :: 3
21 Classifier: Programming Language :: Python :: 3.7
22 Classifier: Programming Language :: Python :: 3.8
23 Classifier: Programming Language :: Python :: 3.9
24 Classifier: Programming Language :: Python :: 3.10
25 Classifier: Programming Language :: Python :: 3.11
26 Classifier: Programming Language :: Python :: Implementation :: CPython
27 Classifier: Topic :: Security
28 Classifier: Topic :: Software Development
29 Requires-Python: ~=3.7
30 Requires-Dist: attrs
31 Requires-Dist: iso8601
32 Requires-Dist: pathspec
33 Requires-Dist: python-dateutil
34 Requires-Dist: securesystemslib[crypto]>=0.28.0
35 Provides-Extra: pynacl
36 Requires-Dist: pynacl>1.2.0; extra == 'pynacl'
37 Description-Content-Type: text/markdown
38
39 # in-toto ![Build](https://github.com/in-toto/in-toto/workflows/Run%20in-toto%20tests%20and%20linter/badge.svg) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1523/badge)](https://bestpractices.coreinfrastructure.org/projects/1523) [![Build status](https://ci.appveyor.com/api/projects/status/taxlhrrlf3co07e1/branch/develop?svg=true)](https://ci.appveyor.com/project/in-toto/in-toto/branch/develop) [![Documentation Status](https://readthedocs.org/projects/in-toto/badge/?version=latest)](https://in-toto.readthedocs.io/en/latest/?badge=latest)
40
41 in-toto provides a framework to protect the integrity of the software supply chain. It does so by verifying that each task in the chain is carried out as planned, by authorized personnel only, and that the product is not tampered with in transit.
42
43 in-toto requires a **project owner** to create a **layout**. A layout lists the sequence of **steps** of the software supply chain, and the **functionaries** authorized to perform these steps.
44 When a functionary performs a step in-toto gathers information about the used command and the related files and stores it in a **link** metadata file. As a consequence link files provide the required evidence to establish a continuous chain that can be validated against the steps defined in the layout.
45
46 The layout, signed by the project owners, together with the links, signed by the designated functionaries, are released as part of the final product, and can be validated manually or via automated tooling in, e.g. a package manager.
47
48
49 ## Getting Started
50
51 ### Installation
52
53 in-toto is available on [PyPI](https://pypi.org/project/in-toto/) and can be
54 installed via [`pip`](https://pypi.org/project/pip/). See
55 [in-toto.readthedocs.io](https://in-toto.readthedocs.io/en/latest/installing.html)
56 to learn about system dependencies and installation alternatives and
57 recommendations.
58
59 ```shell
60 pip install in-toto
61 ```
62 ### Create layout, run supply chain steps and verify final product
63
64 #### Layout
65
66 The in-toto software supply chain layout consists of the following parts:
67 - **expiration date**
68 - **readme** (an optional description of the supply chain)
69 - **functionary keys** (public keys, used to verify link metadata signatures)
70 - **signatures** (one or more layout signatures created with the project owner key(s))
71 - **software supply chain steps**
72 correspond to steps carried out by a functionary as part of the software supply chain. The steps defined in the layout list the functionaries who are authorized to carry out the step (by key id). Steps require a unique name to associate them (upon verification) with link metadata that is created when a functionary carries out the step using the `in-toto` tools. Additionally, steps must have material and product rules which define the files a step is supposed to operate on. Material and product rules are described in the section below.
73 - **inspections** define commands to be run during the verification process and can also list material and product rules.
74
75 Take a look at the [demo layout creation example](https://in-toto.readthedocs.io/en/latest/layout-creation-example.html)
76 for further information on how to create an in-toto layout. Or try our
77 experimental [layout creation web tool](https://in-toto.engineering.nyu.edu/).
78
79
80
81 #### Artifact Rules
82 A software supply chain usually operates on a set of files, such as source code, executables, packages, or the like. in-toto calls these files artifacts. A material is an artifact that will be used when a step or inspection is carried out. Likewise, a product is an artifact that results from carrying out a step.
83
84 The in-toto layout provides a simple rule language to authorize or enforce the artifacts of a step and to chain them together. This adds the following guarantees for any given step or inspection:
85 - Only artifacts **authorized** by the project owner are created, modified or deleted,
86 - each defined creation, modification or deletion is **enforced**, and also
87 - restricted to the scope of its definition, which **chains** subsequent steps and inspections together.
88
89 Note that it is up to you to properly secure your supply chain, by authorizing, enforcing and chaining materials and products using any and usually multiple of the following rules:
90 - `CREATE <pattern>`
91 - `DELETE <pattern>`
92 - `MODIFY <pattern>`
93 - `ALLOW <pattern>`
94 - `DISALLOW <pattern>`
95 - `REQUIRE <file>`
96 - `MATCH <pattern> [IN <source-path-prefix>] WITH (MATERIALS|PRODUCTS) [IN <destination-path-prefix>] FROM <step>`
97
98 *Rule arguments specified as `<pattern>` allow for Unix shell-style wildcards as implemented by Python's [`fnmatch`](https://docs.python.org/3/library/fnmatch.html).*
99
100 in-toto's Artifact Rules, by default, allow artifacts to exist if they are not explicitly disallowed. As such, a `DISALLOW *` invocation is recommended as the final rule for most step definitions. To learn more about the different rule types, their guarantees and how they are applied, take a look at the [Artifact Rules](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#433-artifact-rules) section of the in-toto specification.
101
102 #### Carrying out software supply chain steps
103
104 ##### in-toto-run
105 `in-toto-run` is used to execute a step in the software supply chain. This can
106 be anything relevant to the project such as tagging a release with `git`,
107 running a test, or building a binary. The relevant step name and command are
108 passed as arguments, along with materials, which are files required for that
109 step's command to execute, and products which are files expected as a result
110 of the execution of that command. These, and other relevant details
111 pertaining to the step are stored in a link file, which is signed using the
112 functionary's key.
113
114 If materials are not passed to the command, the link file generated just
115 doesn't record them. Similarly, if the execution of a command via
116 `in-toto-run` doesn't result in any products, they're not recorded in the link
117 file. Any files that are modified or used in any way during the execution of
118 the command are not recorded in the link file unless explicitly passed as
119 artifacts. Conversely, any materials or products passed to the command are
120 recorded in the link file even if they're not part of the execution
121 of the command.
122
123 See [this simple usage example from the demo application
124 for more details](https://github.com/in-toto/demo).
125 For a detailed list of all the command line arguments, run `in-toto-run --help`
126 or look at the [online
127 documentation](https://in-toto.readthedocs.io/en/latest/command-line-tools/in-toto-run.html).
128
129 ##### in-toto-record
130 `in-toto-record` works similar to `in-toto-run` but can be used for
131 multi-part software supply chain steps, i.e. steps that are not carried out
132 by a single command. Use `in-toto-record start ...` to create a
133 preliminary link file that only records the *materials*, then run the
134 commands of that step or edit files manually and finally use
135 `in-toto-record stop ...` to record the *products* and generate the actual
136 link metadata file. For a detailed list of all command line arguments and their usage,
137 run `in-toto-record start --help` or `in-toto-record stop --help`, or look at
138 the [online
139 documentation](https://in-toto.readthedocs.io/en/latest/command-line-tools/in-toto-record.html).
140
141 #### Release final product
142
143 In order to verify the final product with in-toto, the verifier must have access to the layout, the `*.link` files,
144 and the project owner's public key(s).
145
146 #### Verification
147 Use `in-toto-verify` on the final product to verify that
148 - the layout was signed with the project owner's private key(s),
149 - has not expired,
150 - each step was performed and signed by the authorized functionary,
151 - the functionaries used the commands, they were supposed to use,
152 - materials and products of each step were in place as defined by the rules, and
153 - run the defined inspections
154
155 For a detailed list of all command line arguments and their usage, run
156 `in-toto-verify --help` or look at the
157 [online
158 documentation](https://in-toto.readthedocs.io/en/latest/command-line-tools/in-toto-verify.html).
159
160 #### Signatures
161 `in-toto-sign` is a metadata signature helper tool to add, replace, and
162 verify signatures within in-toto Link or Layout metadata, with options to:
163 - replace (default) or add signature(s), with layout metadata able to be
164 signed by multiple keys at once while link metadata can only be signed by one key at a time
165 - write signed metadata to a specified path (if no output path is specified,
166 layout metadata is written to the path of the input file while link metadata
167 is written to `<name>.<keyid prefix>.link`)
168 - verify signatures
169
170 This tool is intended to sign layouts created by the
171 [layout web wizard](https://in-toto.engineering.nyu.edu/), but also serves
172 well to re-sign test and demo data. For example, it can be used if metadata
173 formats or signing routines change.
174
175 For a detailed list of all command line arguments and their usage, run
176 `in-toto-sign --help` or look at the
177 [online
178 documentation](https://in-toto.readthedocs.io/en/latest/command-line-tools/in-toto-sign.html).
179
180
181 ## in-toto demo
182 You can try in-toto by running the [demo application](https://github.com/in-toto/demo).
183 The demo basically outlines three users viz., Alice (project owner), Bob (functionary) and Carl (functionary) and how in-toto helps to specify a project layout and verify that the layout has been followed in a correct manner.
184
185 ## Specification
186 You can read more about how in-toto works by taking a look at the
187 [specification](https://github.com/in-toto/docs/blob/master/in-toto-spec.md).
188
189
190 ## Security Issues and Bugs
191 See [SECURITY.md](SECURITY.md).
192
193
194 ## Governance and Contributing
195
196 For information about in-toto's governance and contributing guidelines, see
197 [GOVERNANCE.md](GOVERNANCE.md).
198
199 ## Acknowledgments
200 This project is managed by Prof. Santiago Torres-Arias at Purdue University.
201 It is worked on by many folks in academia and industry, including members of
202 the [Secure Systems Lab](https://ssl.engineering.nyu.edu/) at NYU and the
203 [NJIT Cybersecurity Research Center](https://centers.njit.edu/cybersecurity).
204
205 This research was supported by the Defense Advanced Research Projects Agency
206 (DARPA), the Air Force Research Laboratory (AFRL), and the US National Science
207 Foundation (NSF). Any opinions, findings, and conclusions or recommendations
208 expressed in this material are those of the authors and do not necessarily
209 reflect the views of DARPA, AFRL, and NSF. The United States Government is
210 authorized to reproduce and distribute reprints notwithstanding any copyright
211 notice herein.