Create srctl tool readme documentation.#190
Open
Daniel-Giszpenc wants to merge 2 commits intokubernetes:mainfrom
Open
Create srctl tool readme documentation.#190Daniel-Giszpenc wants to merge 2 commits intokubernetes:mainfrom
Daniel-Giszpenc wants to merge 2 commits intokubernetes:mainfrom
Conversation
Contributor
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: Daniel-Giszpenc The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
needs-ok-to-test
Contributor
|
Hi @Daniel-Giszpenc. Thanks for your PR. I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with Regular contributors should join the org to skip this step. Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
k8s-ci-robot
added
size/L
Contributor
Author
|
/assign |
Contributor
Author
|
Associated issue: #176 |
mtardy
suggested changes
Apr 13, 2026
Member
mtardy
left a comment
mtardy
left a comment
There was a problem hiding this comment.
Hey thanks for doing this. I feel like this is way too verbose, this is more than 1000 words and around 10k characters. I would expect a good README doc for this simple tool would be 10x less maybe.
Typically a readme is:
- name of the thing
- some paragraphs (one or two?) to introduce the tool, what is it, who is it for (I hope we can condense what you wrote into one or two paragraph with links for more details on the SRC, etc.)
- how to install (could be
go installhere) - usage (could keep what you shown in your output here and the potential output formats, and your usage example by Tabitha)
I think that would be enough.
Comment on lines
+21
to
+53
| ## Why this tool exists: SRC Vulnerability Disclosure Workflow | ||
|
|
||
| ### Understanding the workflow. | ||
|
|
||
| **Step 1:** The [Private Distributors List](https://github.com/kubernetes/committee-security-response/blob/main/security-release-process.md#private-distributors-list) will be given advance notification of any vulnerability that is assigned a CVE, at least 7 days before the planned public disclosure date. | ||
|
|
||
| **Step 2:** Releasing the fix. | ||
|
|
||
| **Step 3:** Public Disclosure | ||
|
|
||
| The announcement will contain the following information: | ||
| - The new releases, the CVE number, severity, and impact, and the location of the binaries to get wide distribution and user action. | ||
| - As much as possible this announcement should be actionable, and include any mitigating steps users can take prior to upgrading to a fixed version. | ||
|
|
||
| The announcement will be sent via the following channels: | ||
| - General announcement email ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-email.md)) to multiple Kubernetes lists | ||
| - OSS-Security announcement email ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-email.md)) to `oss-security@lists.openwall.com` | ||
| - `#announcements` slack channel ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-slack.md)) | ||
| - [discuss.kubernetes.io](https://discuss.kubernetes.io/c/announcements) forum (this should be posted automatically using the general announcement email template) | ||
| - Tracking issue opened in [https://github.com/kubernetes/kubernetes/issues](https://github.com/kubernetes/kubernetes/issues) ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-issue.md)) and prefixed with the associated CVE ID (if applicable). Add `/label official-cve-feed` so it will be part of [https://kubernetes.io/docs/reference/issues-security/official-cve-feed/](https://kubernetes.io/docs/reference/issues-security/official-cve-feed/). Close the issue after the announcement is made. | ||
| - Once all communications are sent, fixes are released, and the CVE data has been populated, close out the public tracking issue. | ||
| - Medium and Low severity vulnerability fixes that will be released as part of the next Kubernetes [patch release](https://github.com/kubernetes/website/blob/main/content/en/releases/patch-releases.md) will have the fix details included in the patch release notes. Any public announcement sent for these fixes will link to the release notes. | ||
| - For Kubernetes core components that are part of a Kubernetes release, provide the CVE feed yaml to the release team, [https://github.com/kubernetes/sig-release/blob/master/release-engineering/role-handbooks/branch-manager.md#announcing-security-fixes](https://github.com/kubernetes/sig-release/blob/master/release-engineering/role-handbooks/branch-manager.md#announcing-security-fixes) | ||
| - After public disclosure, [populate CVE details as soon as possible](https://github.com/kubernetes/committee-security-response/blob/main/cna-handbook.md#populate-cve-details-after-public-disclosure) | ||
|
|
||
| For more details see: | ||
| - https://github.com/kubernetes/committee-security-response/blob/main/security-release-process.md#fix-disclosure-process | ||
|
|
||
| ### What the problem was. | ||
|
|
||
| Vulnerability disclosure needed to be consistently reproduced (no copy paste errors) many times across many communication channels (so reproduce according to many different templates). Additionally, there was need for a more machine friendly OSV feed and SRC is busy enough as can be seen. | ||
|
|
||
| Reducing the report creation workflow to a single writeup process paired with easy automated export processes for the relevant target formats was best to save SRC work, reduce error, and improve usability for the security ecosystem (stable machine-readability). This also makes additional potential channels and formats in the future more approachable. |
Member
There was a problem hiding this comment.
I feel like this is maybe too much to explain the full SRC disclosure workflow, this could be a short paragraph explaining their pain and how this tool tried to fix it.
Suggested change
| ## Why this tool exists: SRC Vulnerability Disclosure Workflow | |
| ### Understanding the workflow. | |
| **Step 1:** The [Private Distributors List](https://github.com/kubernetes/committee-security-response/blob/main/security-release-process.md#private-distributors-list) will be given advance notification of any vulnerability that is assigned a CVE, at least 7 days before the planned public disclosure date. | |
| **Step 2:** Releasing the fix. | |
| **Step 3:** Public Disclosure | |
| The announcement will contain the following information: | |
| - The new releases, the CVE number, severity, and impact, and the location of the binaries to get wide distribution and user action. | |
| - As much as possible this announcement should be actionable, and include any mitigating steps users can take prior to upgrading to a fixed version. | |
| The announcement will be sent via the following channels: | |
| - General announcement email ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-email.md)) to multiple Kubernetes lists | |
| - OSS-Security announcement email ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-email.md)) to `oss-security@lists.openwall.com` | |
| - `#announcements` slack channel ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-slack.md)) | |
| - [discuss.kubernetes.io](https://discuss.kubernetes.io/c/announcements) forum (this should be posted automatically using the general announcement email template) | |
| - Tracking issue opened in [https://github.com/kubernetes/kubernetes/issues](https://github.com/kubernetes/kubernetes/issues) ([template](https://github.com/kubernetes/committee-security-response/blob/main/comms-templates/vulnerability-announcement-issue.md)) and prefixed with the associated CVE ID (if applicable). Add `/label official-cve-feed` so it will be part of [https://kubernetes.io/docs/reference/issues-security/official-cve-feed/](https://kubernetes.io/docs/reference/issues-security/official-cve-feed/). Close the issue after the announcement is made. | |
| - Once all communications are sent, fixes are released, and the CVE data has been populated, close out the public tracking issue. | |
| - Medium and Low severity vulnerability fixes that will be released as part of the next Kubernetes [patch release](https://github.com/kubernetes/website/blob/main/content/en/releases/patch-releases.md) will have the fix details included in the patch release notes. Any public announcement sent for these fixes will link to the release notes. | |
| - For Kubernetes core components that are part of a Kubernetes release, provide the CVE feed yaml to the release team, [https://github.com/kubernetes/sig-release/blob/master/release-engineering/role-handbooks/branch-manager.md#announcing-security-fixes](https://github.com/kubernetes/sig-release/blob/master/release-engineering/role-handbooks/branch-manager.md#announcing-security-fixes) | |
| - After public disclosure, [populate CVE details as soon as possible](https://github.com/kubernetes/committee-security-response/blob/main/cna-handbook.md#populate-cve-details-after-public-disclosure) | |
| For more details see: | |
| - https://github.com/kubernetes/committee-security-response/blob/main/security-release-process.md#fix-disclosure-process | |
| ### What the problem was. | |
| Vulnerability disclosure needed to be consistently reproduced (no copy paste errors) many times across many communication channels (so reproduce according to many different templates). Additionally, there was need for a more machine friendly OSV feed and SRC is busy enough as can be seen. | |
| Reducing the report creation workflow to a single writeup process paired with easy automated export processes for the relevant target formats was best to save SRC work, reduce error, and improve usability for the security ecosystem (stable machine-readability). This also makes additional potential channels and formats in the future more approachable. | |
| Maybe a small paragraph at the end of `## Who this tool is for: The SRC` part? |
Comment on lines
+57
to
+58
| ### CLI Options | ||
|
|
Comment on lines
+103
to
+114
| Notes regarding the file name provided as an argument: | ||
| - must match the following regex expression: `^CVE-\d{4}-\d{4,}$` | ||
| - is valid with or without the ext which is trimmed off | ||
| - if a file with the given valid name | ||
| - does exist in the current directory and the content is fine: the tool will act on the given file | ||
| - does not exist or can't be read by the tool: the tool will create a file with that name and act on that file | ||
|
|
||
| Notes on potential problems | ||
| - incorrect file name error msg: `invalid CVE name` | ||
| - invalid file provided: `error: failed to restore state from file {file name given}: {parsing error}` | ||
| - unable to find editor provided at env-var `$EDITOR` in `$PATH`: `failed to read from editor: failed to run the editor: {execution error}` | ||
| - unable to run editor provided in PATH at `$EDITOR` |
Member
There was a problem hiding this comment.
tbh I wouldn't put that much detail, this feels like it could be quickly outdated and the error displayed by the tool should be enough to understand what went wrong, it should self document
Suggested change
| Notes regarding the file name provided as an argument: | |
| - must match the following regex expression: `^CVE-\d{4}-\d{4,}$` | |
| - is valid with or without the ext which is trimmed off | |
| - if a file with the given valid name | |
| - does exist in the current directory and the content is fine: the tool will act on the given file | |
| - does not exist or can't be read by the tool: the tool will create a file with that name and act on that file | |
| Notes on potential problems | |
| - incorrect file name error msg: `invalid CVE name` | |
| - invalid file provided: `error: failed to restore state from file {file name given}: {parsing error}` | |
| - unable to find editor provided at env-var `$EDITOR` in `$PATH`: `failed to read from editor: failed to run the editor: {execution error}` | |
| - unable to run editor provided in PATH at `$EDITOR` |
Comment on lines
+7
to
+16
| ## Who this tool is for: The SRC | ||
|
|
||
| The Security Response Committee (SRC) is responsible for triaging and handling the security issues for Kubernetes. A committee has the license to do work in private, the SRC is the confidential side of sig-security. The primary goal of this group and their process is to reduce the total time users are vulnerable to publicly known exploits. | ||
|
|
||
| As part of the above responsibility, the SRC is also responsible for organizing the entire project security response including internal communication and external disclosure but will need help from relevant developers and release managers to successfully run this process. | ||
|
|
||
| So the key responsibilities include (with a bit of overlap) | ||
| 1. security incident response for k8s project infrastructure | ||
| 2. the identification, triage, disclosure, and fixing of vulnerabilities | ||
| 3. communication and coordination with relevant parties at the appropriate times |
Member
There was a problem hiding this comment.
I don't think this is the place to document the SRC, I would expect there is some documentation elsewhere that should do the trick that you could link to.
Comment on lines
+116
to
+136
| ### Additional Usage Explanation | ||
|
|
||
| Purpose: For editing particular sections of the report. | ||
| Usage Step: Input from the cli process launched with the tool: `0-9` or letters `a-b` | ||
|
|
||
| Purpose: For saving changed to the report. | ||
| Usage Step: Input from the cli process launched with the tool: `s` | ||
| Note: | ||
| - The tool generates a tmp file which the user operates on in place of the target file during editing so exiting the cli process without telling the tool to save even if saving was done in text editor is not enough. The reasoning here is editing is done back and forth between editor and tool here to work on different sections in isolation easily. | ||
|
|
||
| Purpose: For exporting to any supported format. | ||
| Supported Formats: | ||
| - github issue: [issue.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/issue.tmpl) | ||
| - email: [email.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/email.tmpl) | ||
| - slack: [slack.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/slack.tmpl) | ||
| Usage Steps: | ||
| 1. Input from the cli process launched with the tool: `e` | ||
| 2. Input from the cli process launched with the tool: one of `i` issue `m` mail `s` slack `a` all | ||
| Note: | ||
| - Saving to a JSON file for session state persistence is possible but not a proper disclosure export. | ||
| - The json OSV ([OSV schema](https://ossf.github.io/osv-schema/)) is automatically built for the GitHub Issue. |
Member
There was a problem hiding this comment.
Again this feels like too much detail, the tool should just be self explanatory, otherwise let's fix it. Supported format could be interesting though since it's the output.
Suggested change
| ### Additional Usage Explanation | |
| Purpose: For editing particular sections of the report. | |
| Usage Step: Input from the cli process launched with the tool: `0-9` or letters `a-b` | |
| Purpose: For saving changed to the report. | |
| Usage Step: Input from the cli process launched with the tool: `s` | |
| Note: | |
| - The tool generates a tmp file which the user operates on in place of the target file during editing so exiting the cli process without telling the tool to save even if saving was done in text editor is not enough. The reasoning here is editing is done back and forth between editor and tool here to work on different sections in isolation easily. | |
| Purpose: For exporting to any supported format. | |
| Supported Formats: | |
| - github issue: [issue.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/issue.tmpl) | |
| - email: [email.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/email.tmpl) | |
| - slack: [slack.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/slack.tmpl) | |
| Usage Steps: | |
| 1. Input from the cli process launched with the tool: `e` | |
| 2. Input from the cli process launched with the tool: one of `i` issue `m` mail `s` slack `a` all | |
| Note: | |
| - Saving to a JSON file for session state persistence is possible but not a proper disclosure export. | |
| - The json OSV ([OSV schema](https://ossf.github.io/osv-schema/)) is automatically built for the GitHub Issue. | |
| Supported Formats: | |
| - github issue: [issue.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/issue.tmpl) | |
| - email: [email.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/email.tmpl) | |
| - slack: [slack.tmpl src](https://github.com/kubernetes/sig-security/blob/main/sig-security-tooling/srctl/state/slack.tmpl) |
Comment on lines
+142
to
+145
| ## Implementation | ||
|
|
||
| [tooling: add new CLI for CVE publication by SRC members #171](https://github.com/kubernetes/sig-security/pull/171) | ||
| [`srctl` source directory](https://github.com/kubernetes/sig-security/tree/main/sig-security-tooling/srctl) |
Member
There was a problem hiding this comment.
It's the README I think we should be able to find the sources since there are in the folder we are
Suggested change
| ## Implementation | |
| [tooling: add new CLI for CVE publication by SRC members #171](https://github.com/kubernetes/sig-security/pull/171) | |
| [`srctl` source directory](https://github.com/kubernetes/sig-security/tree/main/sig-security-tooling/srctl) |
k8s-ci-robot
added
size/M
Contributor
Author
|
Thank you for all the feedback. I tried to adjust according to all the comments you gave an respond in one go with this update instead of commenting back on each response, is that a good way of approaching this in the future? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a README for understanding what the
srctltool is, why it exists, and how to use it.