exasol · Nicoretti · Oct 27, 2023 · Oct 23, 2023 · Oct 23, 2023 · Oct 23, 2023
diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -1,7 +1,7 @@
 **< PR SPECIFIC CONTENT >**
 
 -------
-# ✔ Checklist(s) 
+# ✔ Checklist(s)
 
 * [ ] Is the title of the Pull Request correct?
 * [ ] Is the title of the corresponding issue correct?
@@ -10,10 +10,14 @@
 * [ ] Have you checked to ensure there aren't other open Pull Requests for the same update/change?
 * [ ] Are you mentioning the issue which this PullRequest fixes ("Fixes...")
 
+# 🦺 Github Actions
+* [ ] Did you update the version pinning in the action(s)
+  * security-issues (exasol-toolbox)
+
 Note: If any of the above is not relevant to your PR just check the box.
 
-## 🔐 Security 
-## 🐞 Bug 
-## ✨ Feature   
-## 🔧 Refactoring 
-## 📚 Documentation 
+## 🔐 Security
+## 🐞 Bug
+## ✨ Feature
+## 🔧 Refactoring
+## 📚 Documentation
diff --git a/.github/actions/security-issues/action.yml b/.github/actions/security-issues/action.yml
@@ -0,0 +1,65 @@
+name: 'SIA'
+description: 'The Security Issues Action creates github issues for open security issues in the repository'
+
+inputs:
+
+  command:
+    description: 'Command for generating a security report'
+    required: true
+
+  format:
+    description: 'Input format (e.g. "maven" or "pass-through")'
+    required: true
+
+  github-token:
+    description: 'Github Token'
+    required: true
+
+runs:
+
+  using: "composite"
+  steps:
+
+    - name: Setup Python (${{ inputs.python-version}})
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+
+    - name: Install Python Toolbox / Security tool
+      shell: bash
+      run: |
+        pip install exasol-toolbox==0.6.0
+
+    - name: Create Security Issue Report
+      shell: bash
+      run: |
+        ${{ inputs.command }} | tee input
+
+    - name: Convert Report To Common Input Format
+      shell: bash
+      run: |
+        tbx security cve convert ${{inputs.format}} < input | tee cves.jsonl
+
+    - name: Filter Issues
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+      shell: bash
+      run: |
+        tbx security cve filter github-issues < cves.jsonl 2> filtered.txt | tee issues.jsonl
+        cat filtered.txt
+
+    - name: Create Issues
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+      shell: bash
+      run: |
+        tbx security cve create < issues.jsonl | tee created.txt
+
+    - name: Create Report
+      shell: bash
+      run: |
+        echo -e "# Summary\n" >> $GITHUB_STEP_SUMMARY
+        echo -e "## Created Security Issue\n" >> $GITHUB_STEP_SUMMARY
+        cat created.txt >> $GITHUB_STEP_SUMMARY
+        echo -e "## Filtered Security Issue\n" >> $GITHUB_STEP_SUMMARY
+        tail -n +2 filtered.txt | grep . >> $GITHUB_STEP_SUMMARY
diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -6,6 +6,12 @@
 Unreleased
 ==========
 
+✨ Added
+--------
+
+* Added security command
+* Added security-issues action
+
 .. _changelog-0.5.0:
 
 0.5.0 - 2023-10-12

diff --git a/doc/conf.py b/doc/conf.py
@@ -15,14 +15,12 @@
 
 sys.path.insert(0, os.path.abspath("../"))
 
-
 # -- Project information -----------------------------------------------------
 
 project = "Exasol Toolbox"
-copyright = "2022, Exasol"
+copyright = "2022, Exasol"  # pylint: disable=redefined-builtin
 author = "Exasol"
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -60,7 +58,6 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".build-docu"]
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -72,7 +69,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-html_title = f"Toolbox"
+html_title = "Toolbox"
 html_theme_options = {
     "light_logo": "light-exasol-logo.svg",
     "dark_logo": "dark-exasol-logo.svg",

diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst
@@ -7,6 +7,4 @@
 
     ../design
     development
-    todos
-
-
+    ideas
diff --git a/doc/developer_guide/todos.rst → doc/developer_guide/ideas.rst b/doc/developer_guide/todos.rst → doc/developer_guide/ideas.rst
@@ -1,5 +1,5 @@
-📋 Todo's
----------
+📋 Ideas
+--------
 .. todolist::
 
 - Add commit hooks (version check etc.) for the toolbox itself

diff --git a/doc/github_actions/github_actions.rst b/doc/github_actions/github_actions.rst
@@ -0,0 +1,7 @@
+🦺 Github Actions
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    security_issues
diff --git a/doc/github_actions/security_issues.rst b/doc/github_actions/security_issues.rst
@@ -0,0 +1,102 @@
+security-issues
+===============
+
+Example Usage
+-------------
+
+.. code-block:: yaml
+
+    name: Report Security Issues for Repository
+
+    on:
+      schedule:
+        # “Every day at 00:00.” (https://crontab.guru)
+        - cron: "0 0 * * *"
+
+    jobs:
+
+      report_security_issues:
+
+        name: Report Security Issues
+
+        runs-on: ubuntu-latest
+
+        permissions:
+          issues: write
+
+        steps:
+          - name: SCM Checkout
+            uses: actions/checkout@v4
+
+          - name: Report Security Issues
+            uses: exasol/python-toolbox/.github/actions/[email protected]/security-issues-action
+            with:
+              format: "maven"
+              command: "cat maven-cve-report.json"
+              github-token: ${{ secrets.GITHUB_TOKEN }}
+
+Configuration
+-------------
+This action exposes 3 configuration parameters `command`_, `format`_ and `github-token`_, for details see
+the specific sections below.
+
+command
++++++++
+
+Workspace command which shall be executed in order to check the project's dependencies for CVEs.
+
+.. note::
+
+    The calling workflow needs to make sure the specified command can be executed in the context of the workflow.
+
+
+format
+++++++
+
+Specifies converter which needs to be applied on the output of the provided command.
+Currently there are only two converters available
+
+#. maven
+
+    Converts the output of mavens oss plugin into required input format.
+
+
+#. pass-through
+
+    In case the command itself already outputs the expected input format, the format can be specified as code:`pass-through`.
+
+
+Input Format
+------------
+
+The expect intput format is jsonl (line based json), of the following form:
+
+.. code-block:: python
+
+    { "cve": "<cve-id>", "cwe": "<cwe-id>", "description": "<multiline string>", "coordinates": "<string>", "references": ["<url>", "<url>", ...] }
+
+
+.. attention::
+
+    The input format may change in the future. Therefore make sure to rather use or contribute a converter for
+    a specific format rather than outputting this format by your own tooling.
+
+
+github-token
+++++++++++++
+The temporary GitHub token of the workflow needs to be passed into the action (:code:`${{ secrets.GITHUB_TOKEN }}`),
+in order to enable the action to query and created GitHub issues.
+
+
+Ideas
+-----
+
+.. todo::
+
+    Add additional details to the :code:`security.Issue` type
+
+
+.. todo::
+
+    Consider adapting common CVE report format as input, for additional details
+    `see here <https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json>`_.
diff --git a/doc/index.rst b/doc/index.rst
@@ -6,6 +6,7 @@
 
    user_guide/user_guide
    tools
+   github_actions/github_actions
    api
    developer_guide/developer_guide
    changelog
diff --git a/doc/tools.rst b/doc/tools.rst
@@ -1,48 +1,28 @@
 💻 Tools
 ========
 
-tbx
----
-The :code:`tbx` is the main entry point for all of the toolbox specific tooling.
+The python-toolbox ships with a set of command line tools, whose entry point always is the command :code:`tbx`.
+The commands are structured in a *tree* manner, and help is provided along with the command(s) no matter the nesting.
+
+How to get Help
+---------------
 
 .. code-block:: shell
 
      $ tbx --help
 
-     Usage: tbx [OPTIONS] COMMAND [ARGS]...
-
-    ╭─ Options ───────────────────────────────────────────────────────────────────────────╮
-    │ --install-completion          Install completion for the current shell.             │
-    │ --show-completion             Show completion for the current shell, to copy it or  │
-    │                               customize the installation.                           │
-    │ --help                        Show this message and exit.                           │
-    ╰─────────────────────────────────────────────────────────────────────────────────────╯
-    ╭─ Commands ──────────────────────────────────────────────────────────────────────────╮
-    │ workflow                                                                            │
-    ╰─────────────────────────────────────────────────────────────────────────────────────╯
-
-workflow
-++++++++
-The workflow command helps to install and maintain GitHub workflows provided by the toolbox.
-
 .. code-block:: shell
 
-     $ tbx workflow --help
+     $ tbx command --help
 
-     Usage: tbx workflow [OPTIONS] COMMAND [ARGS]...
-
-    ╭─ Options ───────────────────────────────────────────────────────────────────────────╮
-    │ --help          Show this message and exit.                                         │
-    ╰─────────────────────────────────────────────────────────────────────────────────────╯
-    ╭─ Commands ──────────────────────────────────────────────────────────────────────────╮
-    │ diff      Diff a specific workflow against the installed one.                       │
-    │ install   Installs the requested workflow into the target directory.                │
-    │ list      List all available workflows.                                             │
-    │ show      Shows a specific workflow.                                                │
-    │ update    Similar to install but checks for existing workflows and shows diff       │
-    ╰─────────────────────────────────────────────────────────────────────────────────────╯
+.. code-block:: shell
 
+     $ tbx command subcommand --help
 
+.. code-block:: shell
 
+     $ tbx command subcommand subsubcommand --help
 
 
+If the details for a specific command are not sufficient checkout the according subsections bellow,
+or `create an isssue <https://github.com/exasol/python-toolbox/issues/new?assignees=&labels=documentation&projects=&template=documentation.md&title=%F0%9F%93%9A+%3CInsert+Title%3E>`_ if nothing is avialable yet.
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,6 +7,4 @@ @@
         ../design
         development
-        todos
+        ideas