Adding new Security Advisories content to the Academy #1714
Conversation
Signed-off-by: mcaveety <[email protected]>
✅ Deploy Preview for ornate-narwhal-088216 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Did you mean to add the text? My understanding is that it's still in a Google doc? https://docs.google.com/document/d/1Kydf-L0iau640M21aTbjLib00ul3YzH5eJ7muGJZLko/edit#heading=h.ufqupmh2gqkj |
|
I had a look at the Google doc. The lifecycle doc is great! I left a few minor comments. I'm not sure if we want to the wolfictl doc on Academy though -- either the wolfictl repo or wiki seems better to me. We should check with @sheesh though. I've not done a review in GitHub as I don't think the docs are in the PR yet. |
@amouat Oh my goodness, you're right. I was waiting to add the documents since people were still reviewing. Didn't realize I never did that... I'll add them in after I incorporate your edits 😭 sorry about that.
When I asked Dan Luhring about external contributions, I discovered that non-Chainguardians are allowed to submit advisories, and a Chainguardian would then review it before it is included in the advisory database. However, we hadn't discussed the possibility of including the technical guide elsewhere. @luhring would you have any opinions here? Do you think it would fit better on one of the relevant repos? |
Signed-off-by: mcaveety <[email protected]>
They're in there now 😅 |
Yeah, we could probably benefit from having better guidance in the Wolfi advisories repo, for example. This has been an open issue for quite a while 😅 : wolfi-dev/advisories#91 |
@luhring thanks for bringing this up! I'll open a PR on the wolfi advisories repo to share this information, and remove it from this PR. if there's any objections LMK |
Signed-off-by: mcaveety <[email protected]>
|
@smythp this should be ready for a final review whenever you get this chance. I went ahead and removed the technical guide from this PR but kept the conceptual guide, so that should be the only thing you have to review, other than the file structure change since I bucketed two articles together. |
Signed-off-by: mcaveety <[email protected]>
|
I'm not sure why we can't have the security advisory + wolfictl doc in Academy since it is related to Chainguard Images. It's ok for it to be both places if it's also desired within the repo. |
There was a problem hiding this comment.
I left a lot of suggestions, but most of them around comma nitpickery and fixing quotes. I think you have smart quotes turned on, could you do a scan and make sure I didn't miss any?
Otherwise, this is great! I even had a to-do for something like Step 4 assigned to me, so this is super helpful to me!
content/chainguard/chainguard-images/working-with-images/security-advisories/_index.md
Outdated
Show resolved
Hide resolved
...ard/chainguard-images/working-with-images/security-advisories/how-chainguard-issues/index.md
Outdated
Show resolved
Hide resolved
|
|
||
| When you scan a newly-built Chainguard Image with a vulnerability scanner, typically, no CVEs will be reported. However, as software packages age, more vulnerabilities are reported, and CVEs begin to accumulate in images. When this happens, Chainguard releases security advisories to communicate these vulnerabilities to downstream Images users. | ||
|
|
||
| Chainguard publishes its security advisories to a dedicated [Security Advisories page](https://images.chainguard.dev/security/) on its Images Registry. Here, you can find a complete listing of CVEs found in various Chainguard Images, including their CVE ID, affected packages, and vulnerability status. Essentially, these security advisories act as metadata for a security vulnerability. |
There was a problem hiding this comment.
| Chainguard publishes its security advisories to a dedicated [Security Advisories page](https://images.chainguard.dev/security/) on its Images Registry. Here, you can find a complete listing of CVEs found in various Chainguard Images, including their CVE ID, affected packages, and vulnerability status. Essentially, these security advisories act as metadata for a security vulnerability. | |
| Chainguard publishes its security advisories to a dedicated [Security Advisories page](https://images.chainguard.dev/security/) on its Images Directory. There, you can find a complete listing of CVEs found in various Chainguard Images, including their CVE ID, affected packages, and vulnerability status. Each advisory is built from the metadata of a given security vulnerability. |
I lean on calling it the Directory, don't want to folks to confuse it with a regular registry.
Also I thought the last sentence was a bit off, i tried to reframe it
|
|
||
| Chainguard publishes its security advisories to a dedicated [Security Advisories page](https://images.chainguard.dev/security/) on its Images Registry. Here, you can find a complete listing of CVEs found in various Chainguard Images, including their CVE ID, affected packages, and vulnerability status. Essentially, these security advisories act as metadata for a security vulnerability. | ||
|
|
||
|  |
|
|
||
|
|
||
| You can also find consumable Alpine-style `secdb` security advisory feeds at the following URLs: | ||
| [Wolfi OS repository feed](https://github.com/wolfi-dev/os): https://packages.wolfi.dev/os/security.json |
There was a problem hiding this comment.
| [Wolfi OS repository feed](https://github.com/wolfi-dev/os): https://packages.wolfi.dev/os/security.json | |
| * [Wolfi OS repository](https://github.com/wolfi-dev/os) feed: [packages.wolfi.dev/os/security.json](https://packages.wolfi.dev/os/security.json) |
This becomes a muddled paragraph without some fancy formatting, I think this would look better but your call
There was a problem hiding this comment.
I think I lost the formatting from the Google Doc when I copied it over... thanks for pointing this out!
...ard/chainguard-images/working-with-images/security-advisories/how-chainguard-issues/index.md
Outdated
Show resolved
Hide resolved
...ard/chainguard-images/working-with-images/security-advisories/how-chainguard-issues/index.md
Outdated
Show resolved
Hide resolved
...ard/chainguard-images/working-with-images/security-advisories/how-chainguard-issues/index.md
Outdated
Show resolved
Hide resolved
...ard/chainguard-images/working-with-images/security-advisories/how-chainguard-issues/index.md
Outdated
Show resolved
Hide resolved
...ard/chainguard-images/working-with-images/security-advisories/how-chainguard-issues/index.md
Outdated
Show resolved
Hide resolved
🤦 I do have smart quotes on. I remember this being an issue last year too. oops. Thanks for your review, I appreciate it Mark! |
Co-authored-by: Mark Drake <[email protected]> Signed-off-by: Michelle McAveety <[email protected]>
Signed-off-by: mcaveety <[email protected]>
Signed-off-by: mcaveety <[email protected]>
|
8/5: This has been reviewed and approved, I incorporated some changes in additional commits and added a simple table at Adrian's request. There's some ongoing discussion about adding the technical guide to the Academy so if that is done, I will address it in a future PR. see Slack thread: https://chainguard-dev.slack.com/archives/C040R8V1BG9/p1722869159666029 |
There was a bit of back-and-forth regarding whether or not we should include the technical guide for managing security advisories on the Academy, see #1714 for the context. After discussing with @sheesh and others, I believe this article should live on the Academy. The security advisories bucket is a logical place for it to go. This article will benefit Chainguard employees and placing it here will make it more accessible and intuitive to find. There was concern that this article was only suited for internal use, however, a) external users have contributed in the past, although rarely b) if a user wanted to contribute to the advisories repo, they need to do further reading as stated by the article c) any submissions to the repository are audited by an employee before they are merged I don't think this woud necessarily *encourage* external users to contribute or cause noise. If anything, external contributions still benefit anyone using images. To review this article, please test the site locally on your machine and follow the guide. It is suggested that you install wolfictl using the instructions in this tutorial and try out the commands explored in this guide. @SharpRake for review :D sorry, I know I've sent you a lot in a short amount of time! Please take your time 🙏 --------- Signed-off-by: mcaveety <[email protected]> Signed-off-by: Michelle McAveety <[email protected]> Co-authored-by: Mark Drake <[email protected]>
Type of change
New documentation
What should this PR do?
This PR adds two new items to the Academy: An article outlining how Chainguard issues security advisories (i.e. the stages that lead up to the advisory's addition to the database, and how the status labels are chosen and updated as more information is revealed), and a guide explaining how users can use the
wolfictlcommand line tool to view, search, create, and update security advisories.I also opted to move the existing security advisories article (regarding how to use the advisories feed to inform your next steps) into a new bucket simply titled "Security Advisories" so that all three of these documents share the same home.
Resolves https://github.com/chainguard-dev/internal/issues/3303
Resolves https://github.com/chainguard-dev/internal/issues/4061
Why are we making this change?
Customers have expressed confusion with the security advisories page. Namely, customers want to understand how the security advisories page is created. What factors impact the label chosen for the advisory? Our existing documentation on this topic helps users understand the meaning of the advisories, but this new documentation should clarify any lingering questions on how decisions are made under-the-hood. Particularly, questions surrounding "why does my scanner show this and your feed doesn't?" should be answered, as the article walks through the step-by-step process from vulnerability disclosure to advisory creation and remediation. Those curious about the tooling used to issue an advisory can follow the guide using wolfictl to learn how they could do this themselves.
What are the acceptance criteria?
This set of articles should meet the goal set out by both the above explanation and referenced issues. They should be clearly written, technically accurate, and comprehensive on the topic so customers walk away with a better understanding of the security advisories feed.
How should this PR be tested?
Please check out the deploy preview or build the site locally since I've added some changes to the directory hierarchy of some of the articles. Checking style, links, and technical accuracy is also much appreciated.