Add missing help for cimode

README.md

@@ -17,42 +17,39 @@ Python Code Audit is a static application security testing (SAST) tool designed
 This tool is designed for anyone who uses or creates Python programs and wants to understand and mitigate potential security risks.
 
 This tool is created for:
-* Python Users who want to assess the security risks in the Python code they use.
-* Python Developers: Anyone, from professionals to hobbyists, who wants to deliver secure Python code.
-* Security-Conscious Users: People seeking a simple, fast way to gain insight into potential security vulnerabilities within Python packages or files.
+
+- Python Users who want to assess the security risks in the Python code they use.
+- Python Developers: Anyone, from professionals to hobbyists, who wants to deliver secure Python code.
+- Security-Conscious Users: People seeking a simple, fast way to gain insight into potential security vulnerabilities within Python packages or files.
 
 Creating secure software can be challenging. This tool, with its comprehensive [documentation](https://nocomplexity.com/documents/codeaudit/intro.html), acts as your helpful security colleague, making it easier to identify and address vulnerabilities.
 
 ## Features
 
 Python Code Audit has the following features:
 
-* **Vulnerability Detection**: Identifies security vulnerabilities in Python files, essential for package security research.
-
-* **Complexity & Statistics**: Reports security-relevant complexity using a fast, lightweight [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) count via Python's AST.
-
-* **Module Usage & External Vulnerabilities**: Detects used modules and reports known vulnerabilities for used external modules.
-
-* **Inline Issue Reporting**: Shows potential security issues with line numbers and code snippets.
+- **Vulnerability Detection**: Identifies security vulnerabilities in Python files, essential for package security research.
 
+- **Complexity & Statistics**: Reports security-relevant complexity using a fast, lightweight [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) count via Python's AST.
 
-* **External Egress Detection**: Identifies embedded API keys and logic that enables communication with remote services, helping uncover hidden data exfiltration paths.
+- **Module Usage & External Vulnerabilities**: Detects used modules and reports known vulnerabilities for used external modules.
 
-* **CI/CD Ready:** Integrates seamlessly into any CI/CD workflow.
+- **Inline Issue Reporting**: Shows potential security issues with line numbers and code snippets.
 
-* **HTML Reports**: All output is saved in simple, static HTML reports viewable in any browser.
+- **External Egress Detection**: Identifies embedded API keys and logic that enables communication with remote services, helping uncover hidden data exfiltration paths.
 
+- **CI/CD Ready:** Integrates seamlessly into any CI/CD workflow.
 
+- **HTML Reports**: All output is saved in simple, static HTML reports viewable in any browser.
 
 > [!NOTE]
 > Python Code Audit uses the Python's Abstract Syntax Tree (AST) to get robust and reliable result. Using the Python AST makes contextual Vulnerability Detection possible and false positive are minimized.
 
-
 ## Installation
 
 > [!TIP]
 > Try it instantly—no installs, no setup, no excuses.
-> 
+>
 > 👉 Launch the browser version [here](https://nocomplexity.com/codeauditapp/dashboardapp.html)
 
 It runs 100% locally in your browser using WebAssembly (WASM). See the power of the tool in under 60 seconds.
@@ -64,12 +61,8 @@ Loved the browser version? Unlock the full power. For advanced security code ins
 pip install -U codeaudit
 ```
 
-
-
-
 If you have installed **Python Code Audit** previously and want to ensure you are using the latest validations and features, simply run this command again. Python Code Audit is frequently updated with new checks.
 
-
 ## Usage
 
 After installation you can get an overview of all implemented commands. Just type in your terminal:
@@ -82,7 +75,7 @@ This will show all commands:
 
 ```text
 ----------------------------------------------------
- _                    __             _             
+ _                    __             _
 |_) \/_|_|_  _ __    /   _  _| _    |_|    _| o _|_
 |   /  |_| |(_)| |   \__(_)(_|(/_   | ||_|(_| |  |_
 ----------------------------------------------------
@@ -91,13 +84,14 @@ Python Code Audit - A modern Python security source code analyzer based on distr
 
 
 Commands to evaluate Python source code:
-Usage: codeaudit COMMAND <directory|package>  [report.html] 
+Usage: codeaudit COMMAND <directory|package>  [report.html]
 
 Depending on the command, you must specify a local directory, a Python file, or a package name hosted on PyPI.org.Reporting: The results are generated as a static HTML report for viewing in a web browser.
 
 Commands:
   overview             Generates an overview report of code complexity and security indicators.
   filescan             Scans Python source code or PyPI packages for security weaknesses.
+  cimode               Run a SAST scan for CI workflows.
   modulescan           Generate a report on known vulnerabilities in Python modules and packages.
   checks               Creates an HTML report of all implemented security checks.
   version              Prints the module version. Or use codeaudit [-v] [--v] [-version] or [--version].
@@ -107,7 +101,7 @@ Use the Python Code Audit documentation (https://codeaudit.nocomplexity.com) to
 
 ## Example
 
-By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **89 validations** implemented. 
+By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **89 validations** implemented.
 
 The `codeaudit filescan` command shows all **potential** security issues that are detected in the source file in a HTML-report.
 
@@ -129,19 +123,17 @@ Paste the line below directly into your browser bar:
 
 ![Example view of filescan report](filescan.png)
 
-
 ## Contributing
 
 All contributions are welcome! Think of corrections on the documentation, code or more and better tests.
 
 Simple Guidelines:
 
-* Questions, Feature Requests, Bug Reports please use on the Github Issue Tracker.
-
-**Pull Requests are welcome!** 
+- Questions, Feature Requests, Bug Reports please use on the Github Issue Tracker.
 
-When you contribute to Codeaudit, your contributions are made under the same license as the file you are working on. 
+**Pull Requests are welcome!**
 
+When you contribute to Codeaudit, your contributions are made under the same license as the file you are working on.
 
 > [!NOTE]
 > This is an open community driven project. Contributors will be mentioned in the [documentation](https://nocomplexity.com/documents/codeaudit/intro.html).
@@ -150,7 +142,4 @@ We adopt the [Collective Code Construction Contract(C4)](https://rfc.zeromq.org/
 
 ## License
 
-
 `codeaudit` is distributed under the terms of the [GPL-3.0-or-later](https://spdx.org/licenses/GPL-3.0-or-later.html) license.
-
-

docs/cimode.md

@@ -10,16 +10,14 @@ If you have improvements or CI configuration tips, contributions via pull reques
 [Data Exfiltration Detection functionality](data_exfiltration_detection) is not yet available in CI pipelines.
 :::
 
-
 :::{admonition} By default, CI scan mode uses the same analysis engine as the CLI version
 :class: important
 
 So Keep in mind:
 
-* [Some directories are excluded from SAST scanning](excluded_directories)
-* Findings marked with [markissues-label](markissues-label) are ignored by default in CI mode
-:::
-
+- [Some directories are excluded from SAST scanning](excluded_directories)
+- Findings marked with [markissues-label](markissues-label) are ignored by default in CI mode
+  :::
 
 ## CI Mode Command
 
@@ -31,10 +29,8 @@ codeaudit cimode [file|directory] [--output text|html|json] [--nosec True|False]
 
 ### Default behaviour
 
-* Output format: `text`
-* `nosec=True` (ignores lines marked with `# nosec`)
-
-
+- Output format: `text`
+- `nosec=True` (ignores lines marked with `# nosec`)
 
 ### Quick Test Run
 
@@ -46,30 +42,22 @@ codeaudit cimode .
 
 Here, `.` represents the current working directory.
 
-
 ### Command Options
 
-
 | Option         | Description                                                |
-| -------------- | ---------------------------------------------------------- |
+| :------------- | :--------------------------------------------------------- |
 | `-o, --output` | Output format: `text`, `html`, or `json` (default: `text`) |
 | `-n, --nosec`  | Ignore findings marked with `# nosec` (default: `True`)    |
 
-
-
-
 ## GitLab CI Integration
 
-
 Integrating Python Code Audit with [GitLab.com](https://gitlab.com) is straightforward and can be completed in just a few minutes.
 
 For GitLab CI jobs, it is recommended to always save **artifacts**, even when the job fails. This ensures that scan results are available for review in all cases. It is especially useful when using the HTML report format, as it allows you to quickly view findings directly in the browser via the CI artifacts interface.
 
 If needed, you can also export the `json` output for further processing in a separate secure environment, for example to integrate results into dashboards, ticketing systems, or additional analysis pipelines.
 
-
-### HTML report example 
-
+### HTML report example
 
 ```yaml
 # SAST scan with Python Code Audit on GitLab.com
@@ -88,7 +76,7 @@ codeaudit-scan:
     - pip install codeaudit
     - codeaudit --version
     - codeaudit cimode . --output html > codeaudit-output.html
-    
+
   allow_failure: true
 
   artifacts:
@@ -102,8 +90,7 @@ codeaudit-scan:
 
 If a scan detects security weaknesses, the job will fail by default. In many workflows, it is common to allow CI failures so that issues are visible without blocking all development activity.
 
-After the job completes, results are available in the CI **artifacts**. Use *Browse artifacts* to open the HTML report directly in your browser.
-
+After the job completes, results are available in the CI **artifacts**. Use _Browse artifacts_ to open the HTML report directly in your browser.
 
 ### Plain Text Output Example
 
@@ -132,7 +119,6 @@ codeaudit-scan:
     expose_as: "Python Code Audit Report"
 ```
 
-
 ### JSON Output Example
 
 For structured processing or integration with other tools:
@@ -160,6 +146,36 @@ codeaudit-scan:
     expose_as: "Python Code Audit Report"
 ```
 
+### GitLab CI Component Example
+
+`codeaudit` can be easily fitted as a GitLab CI component for easy integration into the GitLab pipelines.
+Example code for a `codeaudit-scan` component:
+
+```yaml
+spec:
+  inputs:
+    python_version:
+      default: "3.14"
+      description: "Python version to use for the scan"
+    stage:
+      default: "scan"
+      description: "Stage to run the scan in"
+    src_dir:
+      default: "."
+      description: "Directory to scan"
+---
+codeaudit-scan:
+  image: python:$[[ inputs.python_version ]]-alpine
+  stage: $[[ inputs.stage ]]
+  before_script:
+    - python -m venv venv
+    - source venv/bin/activate
+    - pip install --upgrade pip codeaudit
+  script:
+    - codeaudit cimode $[[ inputs.src_dir ]]
+```
+
+Example above enforces projects to react on found issues. Intentionally results are not redirected to the file to not cover found issues.
 
 ## GitHub.com CI Integration
 
@@ -200,20 +216,17 @@ jobs:
 
       - name: Run SAST scan
         run: |
-           codeaudit cimode . --output text | tee codeaudit-output.text
-           exit ${PIPESTATUS[0]}
-        
+          codeaudit cimode . --output text | tee codeaudit-output.text
+          exit ${PIPESTATUS[0]}
+
       - name: Upload scan artifact
         uses: actions/upload-artifact@v4
         with:
           name: codeaudit-${{ github.ref_name }}
           path: codeaudit-output.text
-
 ```
 
-
-### HTML output 
-
+### HTML output
 
 ```yaml
 # SAST scan with Python Code Audit on GitHub Actions
@@ -242,7 +255,7 @@ jobs:
 
       - name: Install Python Code Audit
         run: pip install codeaudit
-        
+
       - name: Show version
         run: codeaudit --version
 
@@ -254,11 +267,9 @@ jobs:
         with:
           name: codeaudit-${{ github.ref_name }}
           path: codeaudit-output.html
-
 ```
 
-On GitHub Actions, HTML reports are **not rendered directly in the browser** like a live page. They are stored as **workflow artifacts**. 
-
+On GitHub Actions, HTML reports are **not rendered directly in the browser** like a live page. They are stored as **workflow artifacts**.
 
 To download SAST result artifacts from the workflow run:
 
@@ -271,6 +282,3 @@ After the job finishes:
 5. Download the artifact (usually a `.zip` file)
 6. Extract it locally
 7. Open `codeaudit-output.html` in your browser
-
-
-

src/codeaudit/corecli.py

@@ -18,18 +18,17 @@
 import fire  # for working CLI with this PoC-thing (The Google way)
 
 from codeaudit.__about__ import __version__
+from codeaudit.ci_workflowscan import ci_scan
 from codeaudit.reporting import (
     overview_report,
     report_implemented_tests,
     report_module_information,
     scan_report,
 )
 
-from codeaudit.ci_workflowscan import ci_scan
-
 codeaudit_ascii_art = r"""
 ----------------------------------------------------
- _                    __             _             
+ _                    __             _
 |_) \/_|_|_  _ __    /   _  _| _    |_|    _| o _|_
 |   /  |_| |(_)| |   \__(_)(_|(/_   | ||_|(_| |  |_
 ----------------------------------------------------
@@ -56,13 +55,15 @@ def display_help():
     commands = [
         "overview",
         "filescan",
+        "cimode",
         "modulescan",
         "checks",
         "version",
     ]  # commands on CLI
     functions = [
         overview_report,
         scan_report,
+        ci_scan,
         report_module_information,
         report_implemented_tests,
         display_version,