├── img └── chps-logo.png ├── README.md ├── LICENSE └── CHPs.md /img/chps-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chps-dev/chps/HEAD/img/chps-logo.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Container Hardening Priorities (CHPs) 2 | 3 | CHPs 4 | logo - a bowl of tortilla chips 5 | 6 | This repository provides guidance on objectively classifying container images for security hardening. The [CHPs specification](./CHPs.md) details security criteria across 4 "vectors": 7 | 8 | - **Minimalism** – Reducing software packages and complexity 9 | - **Provenance** – Verifying source and authenticity 10 | - **Configuration & Metadata** – Applying secure defaults and best practices 11 | - **Vulnerabilities** – Tracking known vulnerabilities at any point in time 12 | 13 | ## Why CHPs? 14 | 15 | CHPs help DevOps teams, image authors, and security practitioners quickly see where container images meet or miss security hardening measures. Users can self-assess images and display badges that reflect their security posture. 16 | 17 | ## Getting Started 18 | 19 | 1. **Read the Spec**: See [CHPs.md](./CHPs.md) for the complete classification levels. 20 | 2. **Assess Your Image**: See how well your images rank across the criteria. Use the [CHPs Scorer](https://github.com/chps-dev/chps-scorer) project to do this automatically. 21 | 3. **Badge Your Projects**: Add badges showing how your images score across minimalism, provenance, configuration, and vulnerabilities. 22 | 23 | ## Contributing 24 | 25 | Please open issues or submit pull requests to help refine the specification or suggest new criteria. 26 | 27 | ## License 28 | 29 | All CHPs specification content is provided under the 30 | [Creative Commons BY 4.0 License](./LICENSE). 31 | 32 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public 379 | licenses. Notwithstanding, Creative Commons may elect to apply one of 380 | its public licenses to material it publishes and in those instances 381 | will be considered the “Licensor.” The text of the Creative Commons 382 | public licenses is dedicated to the public domain under the CC0 Public 383 | Domain Dedication. Except for the limited purpose of indicating that 384 | material is shared under a Creative Commons public license or as 385 | otherwise permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the 393 | public licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | -------------------------------------------------------------------------------- /CHPs.md: -------------------------------------------------------------------------------- 1 | # Container Hardening Priorities (CHPs) 2 | 3 | This document describes a method of classifying container images in terms of "security hardening" 4 | levels. 5 | 6 | As an industry, we often talk about container images being "security hardened" or one image being 7 | more secure than another. To date, this has been loosely defined and subjective. This document 8 | attempts an objective classification, enabling comparisons of images and identification of areas for 9 | potential improvement. 10 | 11 | The hope is that this document becomes the beginning of something larger and, to that end, we 12 | encourage discussion and contributions from the community. 13 | 14 | As with any document of this sort, it is impossible to guarantee security and all advice should be 15 | analyzed from your own context. That said, we hope the document is useful in guiding teams to better 16 | practices. 17 | 18 | ## Audience 19 | 20 | The primary audience is DevOps teams trying to assess the security standing of their image 21 | building process, but it can also be used to grade and compare images from third parties. 22 | 23 | Anyone building container images is encouraged to assess their builds according to this document and 24 | publish the results. 25 | 26 | ## Scope 27 | 28 | Scope of this document is limited to OCI Container image development, particularly during build pipelines. 29 | We do not cover runtime configuration, which may be covered a separate document in the 30 | future. For the purposes of this document we assume that the image author is trusted and will not 31 | intentionally insert malware. Software supply chain security is a large focus of this document; 32 | while the original author is considered trusted, details of how images are distributed and verified 33 | are in scope. Application specific vulnerabilities (e.g. buffer overflows or malware in application code) are not 34 | considered although some of the criteria here may reduce the impact of such vulnerabilities. 35 | 36 | The guidance is intended to be applicable to all container build systems, but where specific 37 | advice is given, it is generally assumed Dockerfiles are being used. People using other systems 38 | should be easily able to adapt the advice. 39 | 40 | ## Security Vectors 41 | 42 | This document defines several "vectors" across which container images can be judged. These are: 43 | 44 | - **Minimalism** 45 | 46 | A more "minimal" image will contain less software than a comparative image. Having less 47 | software is useful in terms of reducing "attack surface". If a software package is not present, it 48 | cannot be leveraged in an attack. Note that [image 49 | complexity](https://www.chainguard.dev/unchained/image-sizes-miss-the-point) in terms of number of 50 | packages installed is a better measure of minimalism than raw image size. 51 | 52 | Minimalism becomes particularly important in "living off the land" attacks where trusted, legitimate 53 | tooling is leveraged by the attackers. Reducing the availability of these tools makes attackers' 54 | lives harder. 55 | 56 | - **Provenance** 57 | 58 | Provenance refers to the origin or source of something. In software, we can *prove* the provenance 59 | of artifacts with techniques including cryptographic signatures and checksums. Proving provenance is 60 | the cornerstone of software supply chain security; it is essential to know where your software comes 61 | from and that you are not accidentally running a malicious or tampered version. Note that provenance 62 | extends beyond where container images come from; we also need to consider where all the software 63 | that goes into the container image came from. 64 | 65 | - **Configuration and Metadata** 66 | 67 | There are various configuration settings and patterns for improving container security. For example, 68 | [images should always define a user other than root to run as](#user-is-non-root). 69 | 70 | - **Vulnerabilities** 71 | 72 | Vulnerabilities are exploitable flaws in software. A major goal of security is to reduce the 73 | number of vulnerabilities and their potential impact as much as possible. 74 | 75 | Publicly identified vulnerabilities are are often assigned a Common Vulnerabilities and Exposure 76 | (CVE) identifier on a database such as [National Vulnerability Database 77 | (NVD)](https://nvd.nist.gov/). CVEs are graded from critical to negligible according to perceived 78 | impact. We recommend using tooling (commonly called vulnerability scanners) to check software and 79 | container images for the presence of known CVEs. Readers should not autaomtically dismiss lower 80 | graded CVES, due to the potential impact of _CVE chaining_, where multiple, possibly low impact 81 | vulnerabilities are exploited in combination to achieve a higher-impact attack. 82 | 83 | Because our knowledge of CVEs is constantly evolving, container images can only be graded on this 84 | vector at a point in time; the same image may be CVE free one week but not the next. 85 | 86 | ## Levels 87 | 88 | Providing a long list of suggestions for security hardening risks being overwhelming and 89 | demotivating. In order to mitigate this risk, the advice has been broken into 5 levels. This means 90 | that people new to security can start by working on level 1, without worrying about higher levels 91 | until they have understood and addressed simpler issues. The highest levels are intended to 92 | be aspirational, with few container images meeting this standard. 93 | 94 | It is likely that many container images will meet some items at various levels but not all. In 95 | terms of the vulnerability vector, the level will change over time. So a newly built image may 96 | have no known CVEs (level 5) but next week a new CVE could reduce that level. 97 | 98 | Readers should feel empowered to use the advice in this document as best works for them and their 99 | organization. 100 | 101 | The suggestions are intended to be objectively checkable, so images can be easily (and potentially 102 | automatically) graded. This provides a simple way to compare images against each other, but any 103 | comparisons should always be considered in context; an image that meets all the criteria here may 104 | have security deficiencies not present in an image that only meets a few criteria. This list is not 105 | exhaustive and could not be exhaustive, always practice [defence in 106 | depth](https://en.wikipedia.org/wiki/Defense_in_depth_(computing)) and follow the [principle of 107 | least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). 108 | 109 | In keeping with the salsa and chips theme, the levels have been named after chillis on various 110 | levels of the Scoville scale. 111 | 112 | ## Summary Table 113 | 114 | | Level | Minimalism | Provenance | Configuration & Metadata | Vulnerability | 115 | | ----- | ---------- | ---------- | ------------------------ | --------- | 116 | | **1 Pimiento** | • Use minimal base image | • Download from trusted source | • No secrets in image | | 117 | | | | | | | 118 | | **2 Jalapeno** | • No build or debug tooling | • Verify d/ls by sig or checksum | • No files with elevated privileges |• No critical | 119 | | | | • Sign images | • User is nonroot | | 120 | | | | • Image recently updated | | | 121 | | | | | | | 122 | | **3 Scotch Bonnet** | • No shell | • Pin images to digests | • Support secrets via file mount | • No high | 123 | | | • No package manager | • Pin packages | • Add annotations | | 124 | | | | | | | 125 | | **4 Nagabon** | | • Provenance attestations | | • No medium | 126 | | | | • SBOMs | | | 127 | | | | | | | 128 | | **5 Ghost** | | • Fully reproducible | • Security profile in metadata | • No known CVEs | 129 | 130 | ## Badges 131 | 132 | One of the goals of this project is to provide users with an simple way to differentiate images. As 133 | part of that goal we encourage the use of _badges_ on READMEs and other documentation to describe 134 | where your images are on the CHPs scale e.g: 135 | 136 | ![CHPs Score](https://img.shields.io/badge/overall-A%2B-gold?style=flat-square&labelColor=%233443F4&color=%2301A178) 137 | ![Minimalism](https://img.shields.io/badge/minimalism-A%2B-gold?style=flat-square&labelColor=%233443F4&color=%2301A178) 138 | ![Provenance](https://img.shields.io/badge/provenance-A-gold?style=flat-square&labelColor=%233443F4&color=%2381FEA0) 139 | ![Config](https://img.shields.io/badge/config-C-gold?style=flat-square&labelColor=%233443F4&color=%23F6EB61) 140 | ![Vulns](https://img.shields.io/badge/CVEs-D-gold?style=flat-square&labelColor=%233443F4&color=%23FE5B3C) 141 | 142 | There is a grade per vector and an overall grade. The grades are determined by assigning a point for 143 | each criteria the image meets. This isn't a perfect system, as not all criteria are "equal". We 144 | welcome suggestions for improving the system. 145 | 146 | Note that grades are per image, so a single repository may have multiple images with different tags 147 | e.g. `redis:latest`, `redis:latest-slim`, `redis:latest-debug`. The badges provide a fast, visual way to 148 | identify differences between tags. For example a "debug" image may score lower on the minimalism scale 149 | indicating you may want to use a different tag when deploying to production. 150 | 151 | Grades are ranked according to the percentage of criteria achieved within the relevant vector: 152 | 153 | | % | Grade | 154 | | --- | ----- | 155 | | 100 | A+ | 156 | | 75 | A | 157 | | 50 | B | 158 | | 40 | C | 159 | | - | D | 160 | 161 | At the moment grading is a self-scoring honor system, but there is scope to create an automated grading 162 | system with an API that analyses images and returns a badge. 163 | 164 | ## Discussion by Vector 165 | 166 | Each of the items in the table is discussed in more depth below. Note grouping is by vector rather than level. 167 | 168 | ### Minimalism 169 | 170 | These items all reduce the amount of software packages and complexity in the image. 171 | 172 | #### Use a Minimal Base Image 173 | 174 | Many container base images contain a large set of Linux packages for usability purposes. This is 175 | very helpful when learning containers and in development, but production images should only 176 | contain the packages required by the application being containerized. For example, tools like 177 | curl or wget are very useful for obtaining software in development, but can also be used by an 178 | attacker to obtain malicious tooling or access other parts of the system. 179 | 180 | For this reason, production images should use a slimmed down image such as `debian:slim`, `alpine` 181 | or a distroless image from Chainguard or Google. 182 | 183 | #### No Build or Debug Tooling. 184 | 185 | When building an image, it's common to have a compile step or similar, which requires build tooling 186 | to be present in the image. This tooling should not be present in the final image. This can be 187 | achieved by using a [multi-stage build](https://docs.docker.com/build/building/multi-stage/) where 188 | the built assets are copied onto a new image. 189 | 190 | The same is true for debug tooling. You may have an image build that enables debug tooling such as 191 | debuggers or tracing tools. These options should be turned off in production builds and where 192 | possible the tools should be removed from the image. 193 | 194 | Note that you may well have images breaking this rule in development, but they shouldn't run in 195 | production clusters. 196 | 197 | #### No Shell 198 | 199 | Shells are very useful when developing and debugging images, but they are rarely required for 200 | production images and can provide significant resources to an attacker. 201 | 202 | Removing shells does mean that the traditional debugging technique of `docker exec -it 203 | container_name sh` (and equivalents such as `kubectl exec`) will not work. In these cases you may 204 | want to look at alternative tooling, such as [docker 205 | debug](https://docs.docker.com/reference/cli/docker/debug/), [kubectl 206 | debug](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_debug/) or 207 | [cdebug](https://github.com/iximiuz/cdebug) that can start a temporary process with a shell for 208 | debugging. 209 | 210 | Scripts are also often used in entrypoint scripts and healthchecks. You may be able to replace 211 | entrypoint scripts with a separate and temporary [init 212 | container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) that contains the 213 | tooling, otherwise you will need to replace the script with a compiled binary. 214 | 215 | #### No Package Manager 216 | 217 | Package managers are used to install extra dependencies and tooling. In a production image this will 218 | already have happened, so there is no call for a package manager and removing it can potentially 219 | make attackers have to work harder. 220 | 221 | As the package manager is required by most distribution base images, removing the package manager 222 | typically requires using a multistage build where the final production image runs on a distroless 223 | image, such as [Chainguard's static 224 | image](https://images.chainguard.dev/directory/image/static/overview) or [Google's 225 | distroless](https://github.com/GoogleContainerTools/distroless). 226 | 227 | 228 | ### Provenance 229 | 230 | These items all improve supply-chain security; knowing and proving where the software comes from and 231 | how it was built. 232 | 233 | #### Download From Trusted Source 234 | 235 | It's important to always be aware of who has created the images you're using. In the case of Docker 236 | Hub images, is it an official image? Or a verified publisher? Is the image getting updates? Use 237 | extra caution when pulling images from user repositories with no level of checking or oversight. 238 | Only use images that are being actively maintained. 239 | 240 | #### Verify Downloads 241 | 242 | Nearly all container builds will download or install third party software. If installed via the 243 | package manager (e.g. apt, apk, yum) it will be automatically tested against a checksum to ensure it 244 | hasn't been tampered with. Software downloaded directly (e.g. via `wget` or `curl`) needs separate 245 | checks. This may mean checking signatures, or using a checksum. This will ensure that the artifact 246 | has not been tampered with or replaced. The [Docker official images 247 | guidance](https://github.com/docker-library/official-images?tab=readme-ov-file#security) includes 248 | more information on how to do this correctly. 249 | 250 | Note that the `ADD` statement in Dockerfiles can be used to download software and supports a 251 | [checksum](https://docs.docker.com/reference/dockerfile/#add---checksum) option. This can be useful 252 | in cases where wget or curl is not available in the build image. `ADD` should only be used for remote 253 | files; use `COPY` when adding local files into images. 254 | 255 | #### Sign Images 256 | 257 | Signing container images allows others to verify the origin and authenticity of images and ensures 258 | they haven't been tampered with. 259 | 260 | There are multiple solutions for signing container images, including 261 | [sigstore](https://www.sigstore.dev/) and [notation](https://github.com/notaryproject/notation). 262 | [Keyless signing](https://docs.sigstore.dev/cosign/signing/overview/) means that there is no need to 263 | store a private key, significantly simplifying the set-up and maintenance burden of signing. New 264 | users can refer to this [walkthrough on how to sign an image with cosign](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-sign-a-container-with-cosign/). 265 | 266 | For signing to be effective, signatures must be verified at some point. This can be done in 267 | with CLI tools like [cosign](https://github.com/sigstore/cosign) or platform specific integrations such as 268 | [policy-controller](https://docs.sigstore.dev/policy-controller/overview/) for Kubernetes. 269 | 270 | #### Image Recently Updated 271 | 272 | Images should be regularly rebuilt to ensure they are up-to-date with the latest security fixes. 273 | Even when the code for the main application hasn't changed, it is likely than transitive 274 | dependencies or other software present in the image has. 275 | 276 | Images that have not been updated for an extended period are highly likely to have multiple serious 277 | known vulnerabilities. As a rule of thumb, we would recommend checking that all 3rd party images 278 | have been built in the last 30 days. Anything longer than this suggests that the image is 279 | sporadically maintained. For images that are built within an organisation it should be more often 280 | e.g. weekly or even daily. 281 | 282 | This advice has overlap with the concept of "[build 283 | horizon](https://www.chainguard.dev/unchained/conquering-your-build-horizon)", a practice whereby 284 | assets running in production built before a certain date (the horizon) are automatically rebuilt and 285 | redeployed. 286 | 287 | #### Pin Images to Digests 288 | 289 | Images are normally built on top of other existing images e.g: 290 | 291 | ```Dockerfile 292 | FROM cgr.dev/chainguard/wolfi-base:latest 293 | RUN ... 294 | ``` 295 | 296 | In these cases, it is advisable to pin the image version to a digest. The digest is a content based 297 | hash of the image. If the image changes, the digest will change. This means that rerunning the build 298 | will use exactly the same base image, no matter where the build is done or who performs it. As well 299 | as having benefits for reproducibility, this also reduces the scope for an attacker to replace an 300 | image with a compromised equivalent. 301 | 302 | Pinning to a digest looks like this: 303 | 304 | ```Dockerfile 305 | FROM cgr.dev/chainguard/wolfi-base:latest@sha256:52f88fede0eba350de7be98a4a803be5072e5ddcd8b5c7226d3ebbcd126fb388 306 | RUN apk update ... 307 | ``` 308 | 309 | The downside of pinning images to digests is that it becomes more work to update them; you don't 310 | automatically get a new version or bug-fixes by just rerunning the build. To help automate work like 311 | this, take a look at tools like [frizbee](https://github.com/stacklok/frizbee) and 312 | [digestabot](https://github.com/chainguard-dev/digestabot/). 313 | 314 | #### Pin Packages 315 | 316 | Builds will often install software from a package manager e.g: 317 | 318 | ``` 319 | RUN apk update && apk install curl 320 | 321 | ``` 322 | 323 | In these cases it's advisable to pin the image to the extent supported by the package manager e.g: 324 | 325 | ``` 326 | RUN apk update && apk install curl=8.11.1-r0 327 | 328 | ``` 329 | 330 | Note that in some cases the distribution will not keep old builds of packages, meaning that your 331 | build may break when the package is updated. In these cases, you will need to maintain a package 332 | mirror to guarantee the ability to rebuild old versions of images. 333 | 334 | Again there is a downside to pinning; you will need to regularly update the pins when rebuilding to get new versions and bugfixes. 335 | 336 | #### SLSA Provenance Attestations 337 | 338 | Attestations are verifiable claims related to a software artifact, especially in relation to how it 339 | was produced. These are typically created via the [in-toto framework](https://in-toto.io/), which 340 | defines both the format for attestations and provides a workflow for their creation and 341 | verification. Image builders are encouraged to produce a wide range of attestations, some of which 342 | may be bespoke to a given use case. 343 | 344 | [SLSA Provenance](https://slsa.dev/provenance/v1) defines a standard format that details how an 345 | artifact was built. For example, this will typically include where the source code came from, which 346 | compiler was used with what arguments, when the build started and finished. 347 | 348 | One way to attach in-toto attestations to a container is by using 349 | [cosign](https://docs.sigstore.dev/cosign/) from the Sigstore project. 350 | 351 | #### SBOMs 352 | 353 | [SBOMs](https://en.wikipedia.org/wiki/Software_Bill_of_Materials) or Software Bill of Materials are 354 | a complete list of all the software inside an artifact. An SBOM should specify all the libraries 355 | used and their exact versions. This allows users to determine exactly what is in the container, 356 | which is useful in multiple scenarios, but particularly when assessing organizational exposure to known 357 | vulnerabilities. 358 | 359 | The two most common formats for SBOMs are [SPDX](https://spdx.dev/) and [CycloneDX](https://cyclonedx.org/). 360 | SBOMs are typically linked to a container via an attestation. 361 | 362 | #### Full Reproducibility 363 | 364 | Full reproducibility means that if a build is re-run, the built artifacts will be identical at 365 | the bit level. This is significantly beneficial for supply-chain security as it makes is possible to 366 | prove that an artifact was not tampered with at the build stage. 367 | 368 | Getting to this level of reproducibility with containers is difficult -- a lot of build tooling such 369 | as `docker build` will insert timestamps or unique IDs that break full reproducibility. Projects 370 | that claim success in this space include [apko](https://github.com/chainguard-dev/apko), 371 | [bazel](https://bazel.build/) and 372 | [nix](https://nix.dev/tutorials/nixos/building-and-running-docker-images.html). 373 | 374 | ### Configuration and Metadata 375 | 376 | This vector covers various advice on how to configure Docker Images for security. In many cases this 377 | means creating or configuring metadata that can be applied at runtime. 378 | 379 | #### No Secrets 380 | 381 | Never store secrets in container images. Anyone with access to the image will be able to extract 382 | them. For applications that require secrets at runtime, these should be passed in secure manner when 383 | the container is started. There are multiple solutions for this, but a common technique is to mount 384 | secrets in volumes at runtime. There are also complete enterprise solutions such as the External 385 | Secrets Operator and Vault. 386 | 387 | For secrets that are needed at build time, for example in order to access a download, the container 388 | build tooling should provide a secure feature, for example, see [Docker Build 389 | Secrets](https://docs.docker.com/build/building/secrets/) 390 | 391 | You can check images (and other artifacts) for the presence of secrets via tools such as 392 | [trufflehog](https://github.com/trufflesecurity/trufflehog.) 393 | 394 | #### No files with elevated privileges 395 | 396 | There are two ways in which files can be assigned elevated privileges; by setting the setuid bit 397 | (creating an SUID executable), or by setting capabilities on the file. 398 | 399 | An SUID executable operates with the file owner’s privileges rather than the invoking user’s. This 400 | allows programs to execute with elevated privileges, typically those of the root user. If an 401 | attacker is able to exploit a vulnerability in an SUID executable they may be able to increase their 402 | privileges inside a container. 403 | 404 | Production containers typically do not require SUID executables and they should not be present. SUID 405 | executables can be easily identified e.g. by running this find command: 406 | 407 | ``` 408 | find / -perm -u=s -type f 2>/dev/null 409 | ``` 410 | 411 | In cases where an executable inside a production container does require elevated privileges, 412 | capabilities should be used instead. In the same vein, no files should have elevated capabilities 413 | unless required by the production application. Files with elevated capabilities can be identified 414 | with a similar command, assuming the `getcap` utility is installed: 415 | 416 | ``` 417 | find / -type f -exec getcap '{}' + 2>/dev/null 418 | ``` 419 | 420 | #### User is non-root 421 | 422 | Containers which run as root have elevated access privileges to files and processes in a container. 423 | Should the container or application be compromised, the attacker will gain these raised privileges. 424 | Worse, if the attacker manages to break-out from the container, they will have root privileges on 425 | the host (assuming no other preventions are in place such as user namespacing). For these reasons it 426 | is important that containers do not run as root in production. 427 | 428 | Base images are an exception to this rule as they will typically run as root to allow users 429 | to install software with the package manager. However, base images should be only used in 430 | build workflows and testing; they should not run directly in production. 431 | 432 | Some workflows may require a container to start as root to perform an action such as changing file 433 | permissions. Where possible this action should be moved to an init container. If this is not 434 | possible, the user should be changed to an unprivileged user immediately after performing the 435 | action. 436 | 437 | #### Support Secrets via File 438 | 439 | The classic 12-factor app manifesto advocated for storing configuration in environment variables. This led 440 | to a lot of container images supporting secrets being passed in this manner. This is generally 441 | [considered bad advice](https://blog.arcjet.com/storing-secrets-in-env-vars-considered-harmful/) 442 | now, as they are easily exposed (for example in log output). 443 | 444 | Where possible, containers should support passing secrets by file instead. For example, see the 445 | [postgres official image](https://hub.docker.com/_/postgres/) which supports setting the 446 | `POSTGRES_PASSWORD_FILE` variable, which should point to a file mounted at runtime. 447 | 448 | This can be harder to achieve when containerising third-party software, but consider if you can 449 | create a wrapper script the reads the secret file and passes it to the application in whatever 450 | format it expects. 451 | 452 | #### Add Annotations 453 | 454 | The [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/annotations.md) defines several [annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) which are used to describe features of images in a standard way. Which annotations to use depends on the exact image in question, but common ones include: 455 | 456 | - `org.opencontainers.image.authors` for defining the author of an image (often a company name, 457 | although `vendor` is also used for this purpose) 458 | - `org.opencontainers.image.created` which should contain a timestamp of when the image was built 459 | - `org.opencontainers.image.source` for holding a link to any source repository for the image (e.g. GitHub) 460 | 461 | These annotations can help users identify images and use them correctly, as well as enabling 462 | automation (e.g. indexing the source repository of all images running in a cluster). 463 | 464 | #### Attach a Security Profile 465 | 466 | There are multiple Linux tools (such as kernel security modules) for restricting system calls, 467 | primarily [seccomp](https://docs.docker.com/engine/security/seccomp/), 468 | [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) and 469 | [AppArmor](https://apparmor.net/). These tools work on "profiles" which determine the actions a 470 | program is allowed to take. A default profile can be (and often is) applied to all containers, but 471 | it is also possible to create container specific profiles -- so if a container doesn't need to make 472 | network connections or change file permissions, it can be prevented from doing so. 473 | 474 | Creating a security profile is a non-trivial task, but potentially worthwhile due to the extra 475 | containment and adherence to the least-privilege principle. Profiles can be associated with 476 | container images via attestations. 477 | 478 | ### Vulnerabilities 479 | 480 | This vector is concerned with the number of known 481 | [CVEs](https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures) in the image. These are 482 | normally discovered with an automated tool such as Grype, Trivy or Docker Scout that will "scan" a 483 | container image and return a list of suspected CVEs. There are both Open Source and commercial tools 484 | available. CVEs are normally graded according to the 485 | [CVSS](https://en.wikipedia.org/wiki/Common_Vulnerability_Scoring_System) standard and assigned a 486 | relevant severity: Critical, High, Medium or Low. 487 | 488 | The resultant CVEs can then be investigated and if a CVE is found to be a false-positive or not a 489 | matter of concern, it can be filtered out using a VEX (Vulnerability Exploitability eXchange) 490 | document. There are [tools](https://github.com/openvex/vexctl) available to help build VEX 491 | documents which can be associated with container images via attestations. 492 | 493 | The grading here is only for a point-in-time; new CVEs are constantly being discovered over time, so 494 | the same container image is likely to report more vulnerabilities when scanned at a later date. 495 | 496 | #### No critical 497 | 498 | The image contains no-known critical CVEs. 499 | 500 | #### No high 501 | 502 | The image contains no-known high CVEs. 503 | 504 | #### No medium 505 | 506 | The image contains no-known high CVEs. 507 | 508 | #### No CVEs 509 | 510 | The image contains no-known CVEs. 511 | 512 | ## Thanks 513 | 514 | Thanks to: 515 | - Dustin Kirkland, who came up with the original concept and list. 516 | - Duffie Cooley, Brandon Mitchell, Rory McCune, Jon Johnson, Kyle Crane and Jason Hall for feedback. 517 | --------------------------------------------------------------------------------