diff --git a/README.md b/README.md index 7fbddc9..388ad7e 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,10 @@ 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. @@ -27,32 +28,28 @@ Creating secure software can be challenging. This tool, with its comprehensive [ 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 [report.html] +Usage: codeaudit COMMAND [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. - - diff --git a/docs/cimode.md b/docs/cimode.md index 387900a..be6259d 100644 --- a/docs/cimode.md +++ b/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 - - - diff --git a/src/codeaudit/corecli.py b/src/codeaudit/corecli.py index b46f1c8..b2985ce 100644 --- a/src/codeaudit/corecli.py +++ b/src/codeaudit/corecli.py @@ -18,6 +18,7 @@ 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, @@ -25,11 +26,9 @@ scan_report, ) -from codeaudit.ci_workflowscan import ci_scan - codeaudit_ascii_art = r""" ---------------------------------------------------- - _ __ _ + _ __ _ |_) \/_|_|_ _ __ / _ _| _ |_| _| o _|_ | / |_| |(_)| | \__(_)(_|(/_ | ||_|(_| | |_ ---------------------------------------------------- @@ -56,6 +55,7 @@ def display_help(): commands = [ "overview", "filescan", + "cimode", "modulescan", "checks", "version", @@ -63,6 +63,7 @@ def display_help(): functions = [ overview_report, scan_report, + ci_scan, report_module_information, report_implemented_tests, display_version,