search

kubescape / regolibrary

The regolibrary package contains the controls Kubescape uses for detecting misconfigurations in Kubernetes manifests.
Apache License 2.0
120 stars 48 forks source link

testing PR #565

Closed yuleib closed 9 months ago

yuleib commented 9 months ago

User description

Overview

Type

Enhancement

Description

Changes walkthrough

Relevant files
Enhancement
mk-generator.py
Addition of a script to generate markdown files for controls         
scripts/mk-generator.py - Added a new script to generate markdown files for each control in the
`controls` folder. - The generated markdown files are placed into the `docs/controls`
directory. - Each markdown file contains detailed information about a control, such
as its severity, description, related resources, test, remediation, and
example.
+417/-0 
create-release.yaml
Addition of a step to execute the docs generator script in the create-release workflow
.github/workflows/create-release.yaml - Added a new step to execute the docs generator script.
+3/-1     
sync.yaml
Addition of a workflow to sync documentation of controls library 
.github/workflows/sync.yaml - Added a new workflow to sync documentation of controls library with
`kubescape.io` website. - The workflow checks for any files that are out of sync and opens a
pull request in the target repository with the changes(if any).
+28/-0   
Configuration changes
sync.yaml
Addition of a configuration file for the sync action                         
.github/sync.yaml - Added a new configuration file for the `sync.yml` action. - This file is used to determine which files are to be synced and where.
+7/-0     
✨ Usage guide:
**Overview:** The `describe` tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels. The tool can be triggered [automatically](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) every time a new PR is opened, or can be invoked manually by commenting on a PR. When commenting, to edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L46) related to the describe tool (`pr_description` section), use the following template: ``` /describe --pr_description.some_config1=... --pr_description.some_config2=... ``` With a [configuration file](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-app), use the following template: ``` [pr_description] some_config1=... some_config2=... ```
Enabling\disabling automation
- When you first install the app, the [default mode](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) for the describe tool is: ``` pr_commands = ["/describe --pr_description.add_original_user_description=true" "--pr_description.keep_original_user_title=true", ...] ``` meaning the `describe` tool will run automatically on every PR, will keep the original title, and will add the original user description above the generated description. - Markers are an alternative way to control the generated description, to give maximal control to the user. If you set: ``` pr_commands = ["/describe --pr_description.use_description_markers=true", ...] ``` the tool will replace every marker of the form `pr_agent:marker_name` in the PR description with the relevant content, where `marker_name` is one of the following: - `type`: the PR type. - `summary`: the PR summary. - `walkthrough`: the PR walkthrough. Note that when markers are enabled, if the original PR description does not contain any markers, the tool will not alter the description at all.
Custom labels
The default labels of the `describe` tool are quite generic: [`Bug fix`, `Tests`, `Enhancement`, `Documentation`, `Other`]. If you specify [custom labels](https://github.com/Codium-ai/pr-agent/blob/main/docs/DESCRIBE.md#handle-custom-labels-from-the-repos-labels-page-gem) in the repo's labels page or via configuration file, you can get tailored labels for your use cases. Examples for custom labels: - `Main topic:performance` - pr_agent:The main topic of this PR is performance - `New endpoint` - pr_agent:A new endpoint was added in this PR - `SQL query` - pr_agent:A new SQL query was added in this PR - `Dockerfile changes` - pr_agent:The PR contains changes in the Dockerfile - ... The list above is eclectic, and aims to give an idea of different possibilities. Define custom labels that are relevant for your repo and use cases. Note that Labels are not mutually exclusive, so you can add multiple label categories. Make sure to provide proper title, and a detailed and well-phrased description for each label, so the tool will know when to suggest it.
Utilizing extra instructions
The `describe` tool can be configured with extra instructions, to guide the model to a feedback tailored to the needs of your project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Notice that the general structure of the description is fixed, and cannot be changed. Extra instructions can change the content or style of each sub-section of the PR description. Examples for extra instructions: ``` [pr_description] extra_instructions=""" - The PR title should be in the format: ': ' - The title should be short and concise (up to 10 words) - ... """ ``` Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable. </details></td></tr> <tr><td><details> <summary><strong> More PR-Agent commands</strong></summary><hr> > To invoke the PR-Agent, add a comment using one of the following commands: > - **/review**: Request a review of your Pull Request. > - **/describe**: Update the PR title and description based on the contents of the PR. > - **/improve [--extended]**: Suggest code improvements. Extended mode provides a higher quality feedback. > - **/ask \<QUESTION\>**: Ask a question about the PR. > - **/update_changelog**: Update the changelog based on the PR's contents. > - **/add_docs** 💎: Generate docstring for new components introduced in the PR. > - **/generate_labels** 💎: Generate labels for the PR based on the PR's contents. > - **/analyze** 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. >See the [tools guide](https://github.com/Codium-ai/pr-agent/blob/main/docs/TOOLS_GUIDE.md) for more details. >To list the possible configuration parameters, add a **/config** comment. </details></td></tr> </table> See the [describe usage](https://github.com/Codium-ai/pr-agent/blob/main/docs/DESCRIBE.md) page for a comprehensive guide on using this tool. </details> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/codiumai-pr-agent-free[bot]"><img src="https://avatars.githubusercontent.com/in/354216?v=4" />codiumai-pr-agent-free[bot]</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p><strong><a href="https://github.com/kubescape/regolibrary/pull/565">PR Description</a></strong> updated to latest commit (<a href="https://github.com/kubescape/regolibrary/commit/9513d99d6bb1e3e1c136e22325b66f2ecb314bfa">https://github.com/kubescape/regolibrary/commit/9513d99d6bb1e3e1c136e22325b66f2ecb314bfa</a>)</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/codiumai-pr-agent-free[bot]"><img src="https://avatars.githubusercontent.com/in/354216?v=4" />codiumai-pr-agent-free[bot]</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <h2>PR Analysis</h2> <ul> <li>🎯 <strong>Main theme:</strong> The PR introduces a script to generate markdown files for each control in the <code>controls</code> folder and syncs these files with the <code>kubescape.io</code> website.</li> <li>📝 <strong>PR summary:</strong> The PR adds a new script <code>mk-generator.py</code> that generates markdown files for each control in the <code>controls</code> folder. These markdown files are placed into the <code>docs/controls</code> directory and contain detailed information about each control. The PR also introduces a new configuration file <code>.github/sync.yaml</code> for the <code>sync.yml</code> action and adds a new step to the <code>create-release.yaml</code> workflow to execute the docs generator script. A new workflow <code>.github/workflows/sync.yaml</code> is added to sync the documentation of the controls library with the <code>kubescape.io</code> website.</li> <li>📌 <strong>Type of PR:</strong> Enhancement</li> <li>🧪 <strong>Relevant tests added:</strong> No</li> <li>⏱️ <strong>Estimated effort to review [1-5]:</strong> 4, because the PR introduces a significant amount of new code, including a new script and workflow. It requires a thorough review to ensure the script is working as expected and the workflows are correctly set up.</li> <li>🔒 <strong>Security concerns:</strong> No security concerns found <h2>PR Feedback</h2></li> </ul> <p><strong>💡 General suggestions:</strong> The <code>mk-generator.py</code> script is quite large and complex. It could benefit from being broken down into smaller, more manageable functions. This would make the code easier to understand, maintain, and test. Additionally, it would be beneficial to add some error handling to the script to ensure it fails gracefully and provides useful error messages if something goes wrong. Finally, consider adding some unit tests for the new script to ensure it works as expected and to prevent future regressions.</p> <hr> <details> <summary><strong>✨ Usage guide:</strong></summary><hr> **Overview:** The `review` tool scans the PR code changes, and generates a PR review. The tool can be triggered [automatically](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) every time a new PR is opened, or can be invoked manually by commenting on any PR. When commenting, to edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L19) related to the review tool (`pr_reviewer` section), use the following template: ``` /review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=... ``` With a [configuration file](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-app), use the following template: ``` [pr_reviewer] some_config1=... some_config2=... ``` <table><tr><td><details> <summary><strong> Utilizing extra instructions</strong></summary><hr> The `review` tool can be configured with extra instructions, which can be used to guide the model to a feedback tailored to the needs of your project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify the relevant sub-tool, and the relevant aspects of the PR that you want to emphasize. Examples for extra instructions: ``` [pr_reviewer] # /review # extra_instructions=""" In the code feedback section, emphasize the following: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ ``` Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable. </details></td></tr> <tr><td><details> <summary><strong> How to enable\disable automation</strong></summary><hr> - When you first install PR-Agent app, the [default mode](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) for the `review` tool is: ``` pr_commands = ["/review", ...] ``` meaning the `review` tool will run automatically on every PR, with the default configuration. Edit this field to enable/disable the tool, or to change the used configurations </details></td></tr> <tr><td><details> <summary><strong> About the 'Code feedback' section</strong></summary><hr> The `review` tool provides several type of feedbacks, one of them is code suggestions. If you are interested **only** in the code suggestions, it is recommended to use the [`improve`](https://github.com/Codium-ai/pr-agent/blob/main/docs/IMPROVE.md) feature instead, since it dedicated only to code suggestions, and usually gives better results. Use the `review` tool if you want to get a more comprehensive feedback, which includes code suggestions as well. </details></td></tr> <tr><td><details> <summary><strong> Auto-labels</strong></summary><hr> The `review` tool can auto-generate two specific types of labels for a PR: - a `possible security issue` label, that detects possible [security issues](https://github.com/Codium-ai/pr-agent/blob/tr/user_description/pr_agent/settings/pr_reviewer_prompts.toml#L136) (`enable_review_labels_security` flag) - a `Review effort [1-5]: x` label, where x is the estimated effort to review the PR (`enable_review_labels_effort` flag) </details></td></tr> <tr><td><details> <summary><strong> Extra sub-tools</strong></summary><hr> The `review` tool provides a collection of possible feedbacks about a PR. It is recommended to review the [possible options](https://github.com/Codium-ai/pr-agent/blob/main/docs/REVIEW.md#enabledisable-features), and choose the ones relevant for your use case. Some of the feature that are disabled by default are quite useful, and should be considered for enabling. For example: `require_score_review`, `require_soc2_review`, `enable_review_labels_effort`, and more. </details></td></tr> <tr><td><details> <summary><strong> More PR-Agent commands</strong></summary><hr> > To invoke the PR-Agent, add a comment using one of the following commands: > - **/review**: Request a review of your Pull Request. > - **/describe**: Update the PR title and description based on the contents of the PR. > - **/improve [--extended]**: Suggest code improvements. Extended mode provides a higher quality feedback. > - **/ask \<QUESTION\>**: Ask a question about the PR. > - **/update_changelog**: Update the changelog based on the PR's contents. > - **/add_docs** 💎: Generate docstring for new components introduced in the PR. > - **/generate_labels** 💎: Generate labels for the PR based on the PR's contents. > - **/analyze** 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. >See the [tools guide](https://github.com/Codium-ai/pr-agent/blob/main/docs/TOOLS_GUIDE.md) for more details. >To list the possible configuration parameters, add a **/config** comment. </details></td></tr> </table> See the [review usage](https://github.com/Codium-ai/pr-agent/blob/main/docs/REVIEW.md) page for a comprehensive guide on using this tool. </details> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/codiumai-pr-agent-free[bot]"><img src="https://avatars.githubusercontent.com/in/354216?v=4" />codiumai-pr-agent-free[bot]</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <h2>PR Code Suggestions</h2> <table><thead><tr><th></th><th>Suggestions                                                                                                                                                          </th></tr></thead><tbody><tr><td><strong>best practice</strong></td><td><table><tr><td> <details><summary>Ensure proper file handling by using <code>with</code> statement.            </summary> ___ **The `json.load()` function is used with a file object that is not closed properly. It's a <br> good practice to use the `with` statement when dealing with file objects. This has the <br> advantage that the file is properly closed after its suite finishes, even if an exception <br> is raised at some point.** [scripts/mk-generator.py [42]](https://github.com/kubescape/regolibrary/pull/565/files#diff-10e28221e31725d4773e6d6ead19e8bd87716472b82bd3d14660bd796d19ada4R42-R42) ```diff -framework = json.load(open(os.path.join('frameworks',frameworks_json_file_name))) +with open(os.path.join('frameworks',frameworks_json_file_name)) as f: + framework = json.load(f) ``` </details></td></tr></table></td></tr><tr><td><strong>enhancement</strong></td><td><table><tr><td> <details><summary>Simplify multiple <code>or</code> conditions with <code>any</code> function. </summary> ___ **The `ignore_framework` function currently uses an `or` condition to check if the framework <br> name is 'YAML-scanning' or starts with 'developer'. This can be simplified by using a <br> tuple with the conditions and the `any` function.** [scripts/mk-generator.py [24]](https://github.com/kubescape/regolibrary/pull/565/files#diff-10e28221e31725d4773e6d6ead19e8bd87716472b82bd3d14660bd796d19ada4R24-R24) ```diff -return framework_name == 'YAML-scanning' or framework_name.startswith('developer') +return any((framework_name == 'YAML-scanning', framework_name.startswith('developer'))) ``` </details></td></tr><tr><td> <details><summary>Simplify file filtering with list comprehension.                             </summary> ___ **The `get_frameworks_for_control` function uses a filter and a lambda function to get all <br> the json files in the 'frameworks' directory. This can be simplified by using a list <br> comprehension with a conditional statement.** [scripts/mk-generator.py [41]](https://github.com/kubescape/regolibrary/pull/565/files#diff-10e28221e31725d4773e6d6ead19e8bd87716472b82bd3d14660bd796d19ada4R41-R41) ```diff -for frameworks_json_file_name in filter(lambda fn: fn.endswith('.json'),os.listdir('frameworks')): +for frameworks_json_file_name in [fn for fn in os.listdir('frameworks') if fn.endswith('.json')]: ``` </details></td></tr></table></td></tr><tr><td><strong>performance</strong></td><td><table><tr><td> <details><summary>Use list to build large strings instead of string concatenation.             </summary> ___ **The `create_md_for_control` function uses string concatenation to build the markdown text. <br> This can be inefficient for large strings. It's better to use a list to store the strings <br> and then join them at the end.** [scripts/mk-generator.py [91-92]](https://github.com/kubescape/regolibrary/pull/565/files#diff-10e28221e31725d4773e6d6ead19e8bd87716472b82bd3d14660bd796d19ada4R91-R92) ```diff -md_text = '' -md_text += '# %s - %s\n' % (control['controlID'], control['name']) + '\n' +md_text = [] +md_text.append('# %s - %s\n' % (control['controlID'], control['name']) + '\n') +# ... other append operations ... +md_text = ''.join(md_text) ``` </details></td></tr></table></td></tr></tr></tbody></table><hr> <details> <summary><strong>✨ Usage guide:</strong></summary><hr> **Overview:** The `improve` tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered [automatically](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) every time a new PR is opened, or can be invoked manually by commenting on a PR. When commenting, to edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L69) related to the improve tool (`pr_code_suggestions` section), use the following template: ``` /improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=... ``` With a [configuration file](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-app), use the following template: ``` [pr_code_suggestions] some_config1=... some_config2=... ``` <table><tr><td><details> <summary><strong> Enabling\disabling automation </strong></summary><hr> When you first install the app, the [default mode](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) for the improve tool is: ``` pr_commands = ["/improve --pr_code_suggestions.summarize=true", ...] ``` meaning the `improve` tool will run automatically on every PR, with summarization enabled. Delete this line to disable the tool from running automatically. </details></td></tr> <tr><td><details> <summary><strong> Utilizing extra instructions</strong></summary><hr> Extra instructions are very important for the `improve` tool, since they enable to guide the model to suggestions that are more relevant to the specific needs of the project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on. Examples for extra instructions: ``` [pr_code_suggestions] # /improve # extra_instructions=""" Emphasize the following aspects: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ ``` Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable. </details></td></tr> <tr><td><details> <summary><strong> A note on code suggestions quality</strong></summary><hr> - While the current AI for code is getting better and better (GPT-4), it's not flawless. Not all the suggestions will be perfect, and a user should not accept all of them automatically. - Suggestions are not meant to be simplistic. Instead, they aim to give deep feedback and raise questions, ideas and thoughts to the user, who can then use his judgment, experience, and understanding of the code base. - Recommended to use the 'extra_instructions' field to guide the model to suggestions that are more relevant to the specific needs of the project. - Best quality will be obtained by using 'improve --extended' mode. </details></td></tr> <tr><td><details> <summary><strong> More PR-Agent commands</strong></summary><hr> > To invoke the PR-Agent, add a comment using one of the following commands: > - **/review**: Request a review of your Pull Request. > - **/describe**: Update the PR title and description based on the contents of the PR. > - **/improve [--extended]**: Suggest code improvements. Extended mode provides a higher quality feedback. > - **/ask \<QUESTION\>**: Ask a question about the PR. > - **/update_changelog**: Update the changelog based on the PR's contents. > - **/add_docs** 💎: Generate docstring for new components introduced in the PR. > - **/generate_labels** 💎: Generate labels for the PR based on the PR's contents. > - **/analyze** 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. >See the [tools guide](https://github.com/Codium-ai/pr-agent/blob/main/docs/TOOLS_GUIDE.md) for more details. >To list the possible configuration parameters, add a **/config** comment. </details></td></tr> </table> See the [improve usage](https://github.com/Codium-ai/pr-agent/blob/main/docs/IMPROVE.md) page for a more comprehensive guide on using this tool. </details> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/github-actions[bot]"><img src="https://avatars.githubusercontent.com/in/15368?v=4" />github-actions[bot]</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>Summary:</p> <ul> <li>License scan: failure</li> <li>Credentials scan: failure</li> <li>Vulnerabilities scan: failure</li> <li>Unit test: success</li> <li>Go linting: success</li> </ul> </div> </div> <div class="page-bar-simple"> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>