codeaudit 1.4.0__tar.gz → 1.4.2__tar.gz

{codeaudit-1.4.0 → codeaudit-1.4.2}/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Change Log
 
+## Version 1.4.2: API updates and fixes
+
+Added:
+* Remote Package Scanning: The codeaudit.api_interfaces.filescan(input_path) function now supports PyPI.org packages directly. Users can scan packages by name without needing to clone the repository locally first.
+
+Changed:
+* CLI Improvements: Refined the command-line interface (CLI) help text for better clarity and updated information.
+
+Fixed:
+* Help Command Shortcut: Fixed an issue where the -? flag did not correctly trigger the help text. Running codeaudit [command] -? now displays the expected documentation.
+
+Documentation:
+* Performed a manual updates to improve readability and technical accuracy.
+
+
+## Version 1.4.1: Bug fixes
+
+🚀 New Features & Enhancements
+* Remote PyPI Auditing: The `codeaudit overview <directory|package>` command now supports creating an overview from packages hosted on PyPI.org. Consequently, local cloning is no longer required!
+
+
+🛠 Bug Fixes
+* Improved sdist Resilience: Enhanced error handling for scenarios where a package exists on PyPI but a source distribution (sdist) is unavailable. 
+
+
+📝 Documentation & UI Updates
+* CLI Improvements: Refined terminal text and messaging for better clarity during operation.
+* Manual Update: The user manual has been updated to reflect new command capabilities and workflows.
+
+
 ## Version 1.4: Changes and Updates
 
 

{codeaudit-1.4.0 → codeaudit-1.4.2}/CONTRIBUTE.md

@@ -2,12 +2,13 @@
 
 Great that you see this page and want to contribute!
 
-:::{tip}
-All contributions are welcome!
-Think of corrections on the manual, code and more or better tests.
-:::
+> [!TIP]
+>
+> All contributions are welcome!
+> Think of corrections on the manual, code and more or better tests.
 
-The **Codeaudit** code repository is hosted at [Github](github.com/nocomplexity/codeaudit).
+
+The **Python Code Audit** code repository is hosted at [Github](github.com/nocomplexity/codeaudit).
 
 Simple Guidelines:
 
@@ -16,25 +17,25 @@ Simple Guidelines:
 
 This codeaudit tool is designed by applying [Zero Complexity By Design principles](https://nocomplexity.com/documents/0complexity/abstract.html). So the goal is to keep the tool simple to use and the code simple to adjust or to extend.
 
-:::{warning}
-This simple tool is designed to be simple to use and maintain. 
-:::
+
+> [!IMPORTANT]
+> This simple tool is designed to be simple to use and maintain. 
+
 
 **Pull Requests are welcome!** 
 
-When you contribute to Codeaudit, your contributions are made under the same license as the file you are working on. 
+When you contribute to **Python Code Audit**, your contributions are made under the same license as the file you are working on. 
 
 
 We adopt the [Collective Code Construction Contract(C4)](https://rfc.zeromq.org/spec/42/) to streamline collaboration. C4 is meant to provide a reusable optimal collaboration model for open source software projects. 
 
-:::{attention} 
-This project values respect and inclusiveness, and enforces a [Code of Conduct](CoC-label) in all interactions.
-:::
+> [!IMPORTANT]
+> This project values respect and inclusiveness, and enforces a [Code of Conduct](CoC-label) in all interactions.
+
 
+> [!NOTE]
+> This is an open community driven project. Contributors will be mentioned in the documentation.
 
-:::{note} 
-This is an open community driven project. Contributors will be mentioned in the documentation.
-:::
 
 (CoC-label)=
 ## Code of Conduct

{codeaudit-1.4.0 → codeaudit-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeaudit
-Version: 1.4.0
+Version: 1.4.2
 Summary: Simplified static security checks for Python 
 Project-URL: Documentation, https://github.com/nocomplexity/codeaudit#readme
 Project-URL: Issues, https://github.com/nocomplexity/codeaudit/issues
@@ -74,17 +74,12 @@ Python Code Audit has the following features:
 
 ## Installation
 
-```console
-pip install codeaudit
-```
-
-or use:
-
 ```console
 pip install -U codeaudit
 ```
 
-If you have installed Python `codeaudit` in the past and want to make sure you use the latest new validations and features.
+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
 
@@ -106,34 +101,32 @@ This will show all commands:
 Python Code Audit - A modern Python security source code analyzer based on distrust.
 
 Commands to evaluate Python source code:
-Usage: codeaudit COMMAND [PATH or FILE]  [OUTPUTFILE] 
+Usage: codeaudit COMMAND <directory|package>  [report.html] 
 
-Depending on the command, a directory or file name must be specified. The output is a static HTML file to be examined in a browser. Specifying a name for the output file is optional.
+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             Reports Complexity and statistics per Python file from a directory.
-  filescan             Scans Python files or directories(packages) for vulnerabilities and reports potential issues.
-  modulescan           Reports module vulnerability information.
+  overview             Generates an overview report of code complexity and security indicators.
+  filescan             Scans Python source code or PyPI packages for security weaknesses.
+  modulescan           Generates a vulnerability report for imported Python modules.
   checks               Creates an HTML report of all implemented security checks.
   version              Prints the module version. Or use codeaudit [-v] [--v] [-version] or [--version].
 
-Use the Codeaudit documentation to check the security of Python programs and make your Python programs more secure!
-Check https://simplifysecurity.nocomplexity.com/ 
-
+Use the Python Code Audit documentation (https://codeaudit.nocomplexity.com) to audit and secure your Python programmes. Explore further essential open-source security tools at https://simplifysecurity.nocomplexity.com/
 ```
 
 ## Example
 
-By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **70 validations** implemented. 
+By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **80 validations** implemented. 
 
 The `codeaudit filescan` command shows all **potential** security issues that are detected in the source file in a HTML-report.
 
 Per line a the in construct that can cause a security risks is shown, along with the relevant code lines where the issue is detected.
 
-To scan a Python file on possible security issues, do:
+To scan a Python package on PyPI.org on possible security issues, do:
 
 ```bash
-codeaudit filescan ../codeaudit/tests/validationfiles/allshit.py 
+codeaudit filescan <package-name> [reportname.html]
 
 =====================================================================
 Codeaudit report file created!

{codeaudit-1.4.0 → codeaudit-1.4.2}/README.md

@@ -46,17 +46,12 @@ Python Code Audit has the following features:
 
 ## Installation
 
-```console
-pip install codeaudit
-```
-
-or use:
-
 ```console
 pip install -U codeaudit
 ```
 
-If you have installed Python `codeaudit` in the past and want to make sure you use the latest new validations and features.
+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
 
@@ -78,34 +73,32 @@ This will show all commands:
 Python Code Audit - A modern Python security source code analyzer based on distrust.
 
 Commands to evaluate Python source code:
-Usage: codeaudit COMMAND [PATH or FILE]  [OUTPUTFILE] 
+Usage: codeaudit COMMAND <directory|package>  [report.html] 
 
-Depending on the command, a directory or file name must be specified. The output is a static HTML file to be examined in a browser. Specifying a name for the output file is optional.
+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             Reports Complexity and statistics per Python file from a directory.
-  filescan             Scans Python files or directories(packages) for vulnerabilities and reports potential issues.
-  modulescan           Reports module vulnerability information.
+  overview             Generates an overview report of code complexity and security indicators.
+  filescan             Scans Python source code or PyPI packages for security weaknesses.
+  modulescan           Generates a vulnerability report for imported Python modules.
   checks               Creates an HTML report of all implemented security checks.
   version              Prints the module version. Or use codeaudit [-v] [--v] [-version] or [--version].
 
-Use the Codeaudit documentation to check the security of Python programs and make your Python programs more secure!
-Check https://simplifysecurity.nocomplexity.com/ 
-
+Use the Python Code Audit documentation (https://codeaudit.nocomplexity.com) to audit and secure your Python programmes. Explore further essential open-source security tools at https://simplifysecurity.nocomplexity.com/
 ```
 
 ## Example
 
-By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **70 validations** implemented. 
+By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **80 validations** implemented. 
 
 The `codeaudit filescan` command shows all **potential** security issues that are detected in the source file in a HTML-report.
 
 Per line a the in construct that can cause a security risks is shown, along with the relevant code lines where the issue is detected.
 
-To scan a Python file on possible security issues, do:
+To scan a Python package on PyPI.org on possible security issues, do:
 
 ```bash
-codeaudit filescan ../codeaudit/tests/validationfiles/allshit.py 
+codeaudit filescan <package-name> [reportname.html]
 
 =====================================================================
 Codeaudit report file created!

{codeaudit-1.4.0 → codeaudit-1.4.2}/docs/CLIcommands.ipynb

@@ -90,7 +90,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": null,
    "id": "bf6afe56-e0f7-4fa2-a3a5-968bad11bf9c",
    "metadata": {},
    "outputs": [],
@@ -101,7 +101,7 @@
     "                \"checks\" : 'report_implemented_tests',\n",
     "               \"version\" : 'display_version'} \n",
     "for key, value in commands.items():    \n",
-    "    output += f'## Code Audit {key}\\n' # newlines matter when creating markdown\n",
+    "    output += f'## codeaudit {key}\\n' # newlines matter when creating markdown\n",
     "    output += '```text\\n' # raw display    \n",
     "    func_name = value\n",
     "    output += getattr(codeaudit, func_name).__doc__\n",

{codeaudit-1.4.0 → codeaudit-1.4.2}/docs/CONTRIBUTE.md

@@ -4,8 +4,22 @@ Great that you want to contribute!
 
 :::{tip}
 All contributions are welcome!
-
 Think of corrections on the manual, code and more or better tests.
+
++++
+
+Not a coder? Not a problem! **Python Code Audit** is multifaceted, so I always can use help. 
+These are all activities we’d like to get help with :
+- Writing and improving the documentation 
+- Code maintenance and development
+- Community coordination
+- Advocating Python secure programming 
+- Developing educational content 
+- Fundraising 
+- Marketing
+- Project management
+- Translating content
+- Website design and development
 :::
 
 The **Codeaudit** code repository is hosted at [Github](https://github.com/nocomplexity/codeaudit).

{codeaudit-1.4.0 → codeaudit-1.4.2}/docs/_toc.yml

@@ -67,6 +67,8 @@ parts:
   - file: apidocs/api_intro
     sections:    
     - file: examples/ca_api_example_overview
+    - file: examples/ca_api_example_checks
+    - file: examples/ca_api_example_scanning
     - file: examples/ca_api_example_json
     - file: examples/ca_api_example_basic
   - file: apidocs/modules

codeaudit-1.4.2/docs/apidocs/api_intro.md

@@ -0,0 +1,26 @@
+# APIs and Examples
+
+The Python Code Audit APIs empower you to build your own Python security tools or create seamless integrations you need! Leverage our standardized JSON output to enhance your development workflow in the following ways:
+
+* **Automated Scanning**: Perform deep security analysis on local files, directories, or PyPI.org packages. Use the structured JSON output to trigger custom logic or automated remediation.
+
++++
+
+* **Custom Reporting & Dashboards**: Transform audit results into visual insights. The human-readable JSON export makes it easy to feed data into custom monitoring dashboards or BI tools.
+
++++
+
+
+* **Security Statistical Analysis**: Identify trends and recurring vulnerabilities. Use the APIs to study security weaknesses across your organization’s entire Python ecosystem to improve coding standards.
+
++++
+
+
+* **Seamless CI/CD Integration**: Embed security audits directly into your deployment pipelines. The APIs fully support remote source control systems, including GitHub, GitLab, [Codeberg](https://codeberg.org/), [NotABug](https://notabug.org/), and other Git-based platforms.
+
+## Getting Started
+We have provided several practical examples to help you implement these APIs effectively and secure your codebase with minimal friction.
+
+
+```{tableofcontents}
+```

codeaudit-1.4.2/docs/codeauditcommands.md

@@ -0,0 +1,230 @@
+% THIS FILE IS GENERATED! - Use CLIcommands.ipynb to make it better!
+# Commands Overview
+Python Code Audit commands for: version: 1.4.2
+```
+----------------------------------------------------
+ _                    __             _             
+|_) \/_|_|_  _ __    /   _  _| _    |_|    _| o _|_
+|   /  |_| |(_)| |   \__(_)(_|(/_   | ||_|(_| |  |_
+----------------------------------------------------
+
+Python Code Audit - A modern Python security source code analyzer based on distrust.
+
+Commands to evaluate Python source code:
+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.
+  modulescan           Generates a vulnerability report for imported Python modules.
+  checks               Creates an HTML report of all implemented security checks.
+  version              Prints the module version. Or use codeaudit [-v] [--v] [-version] or [--version].
+
+Use the Python Code Audit documentation (https://codeaudit.nocomplexity.com) to audit and secure your Python programmes. Explore further essential open-source security tools at https://simplifysecurity.nocomplexity.com/
+
+```
+## codeaudit overview
+```text
+Generates an overview report of code complexity and security indicators.
+
+This function analyzes a Python project to produce a high-level overview of
+complexity and security-related metrics. The input may be either:
+
+- A local directory containing Python source files
+- The name of a package hosted on PyPI.org
+
+For PyPI packages, the source distribution (sdist) is downloaded,
+extracted to a temporary directory, scanned, and removed after the report
+is generated.
+
+The report includes summary statistics, security risk indicators based on
+complexity and total lines of code, a list of discovered modules, per-file
+metrics, and a visual overview. Results are written to a static HTML file.
+
+Examples:
+    Generate an overview report for a local project directory::
+
+        codeaudit overview /projects/mycolleaguesproject
+
+    Generate an overview report for a PyPI package::
+
+        codeaudit overview linkaudit #A nice project on PyPI.org
+
+        codeaudit overview pydantic  #A complex project on PyPI.org from a security perspective?
+
+Args:
+    directory (str): Path to a local directory containing Python source files
+        or the name of a package available on PyPI.org.
+    filename (str, optional): Name (and optional path) of the HTML file to
+        write the overview report to. The filename should use the ``.html``
+        extension. Defaults to ``DEFAULT_OUTPUT_FILE``.
+
+Returns:
+    None. The function writes a static HTML overview report to disk.
+
+Raises:
+    SystemExit: If the provided path is not a directory, contains no Python
+        files, or is neither a valid local directory nor a valid PyPI
+        package name.    
+str(object='') -> str
+str(bytes_or_buffer[, encoding[, errors]]) -> str
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.__str__() (if defined)
+or repr(object).
+encoding defaults to 'utf-8'.
+errors defaults to 'strict'.
+```
+## codeaudit modulescan
+```text
+Generates a vulnerability report for imported Python modules.
+
+This function analyzes a single Python source file to identify imported
+modules and checks externally imported modules against the OSV vulnerability
+database. The results are compiled into a static HTML report.
+
+For each detected external module, the report indicates whether known
+vulnerability information exists and, if available, includes detailed
+vulnerability data.
+
+Progress information is printed to stdout while processing modules.
+
+Example:
+    Generate a module vulnerability report for a Python file::
+
+        codeaudit modulescan mypythonfile.py 
+
+Args:
+    inputfile (str): Path to the Python source file to analyze.
+    reportname (str, optional): Name (and optional path) of the HTML file
+        to write the module vulnerability report to. The filename should
+        use the ``.html`` extension. Defaults to ``DEFAULT_OUTPUT_FILE``.
+
+Returns:
+    None. The function writes a static HTML report to disk.
+
+Raises:
+    None explicitly. File reading errors or invalid input are reported
+    via standard output.
+
+str(object='') -> str
+str(bytes_or_buffer[, encoding[, errors]]) -> str
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.__str__() (if defined)
+or repr(object).
+encoding defaults to 'utf-8'.
+errors defaults to 'strict'.
+```
+## codeaudit filescan
+```text
+Scans Python source code or PyPI packages for security weaknesses.
+
+This function performs static application security testing (SAST) on a
+given input, which can be:
+
+- A local directory containing Python source code
+- A single local Python file 
+- A package name hosted on PyPI.org
+
+Depending on the input type, the function analyzes the source code for
+potential security issues, generates an HTML report summarizing the
+findings, and writes the report to a static HTML file.
+
+If a PyPI package name is provided, the function downloads the source
+distribution (sdist), scans the extracted source code, and removes all
+temporary files after the scan completes.
+
+Example:
+    Scan a local directory and write the report to ``report.html``::
+
+        codeaudit filescan_/shitwork/custompythonmodule/ 
+
+    Scan a single Python file::
+
+        codeaudit filescan myexample.py
+
+    Scan a package hosted on PyPI::
+
+        codeaudit filescan linkaudit  #A nice project to check broken links in markdown files
+
+        codeaudit filescan requests
+
+Args:
+    input_path (str): Path to a local Python file or directory, or the name
+        of a package available on PyPI.org.
+    filename (str, optional): Name (and optional path) of the HTML file to
+        write the scan report to. The filename should use the ``.html``
+        extension. Defaults to ``DEFAULT_OUTPUT_FILE``.
+
+Returns:
+    None. The function writes a static HTML security report to disk.
+
+Raises:
+    None explicitly. Errors and invalid inputs are reported to stdout.    
+str(object='') -> str
+str(bytes_or_buffer[, encoding[, errors]]) -> str
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.__str__() (if defined)
+or repr(object).
+encoding defaults to 'utf-8'.
+errors defaults to 'strict'.
+```
+## codeaudit checks
+```text
+
+Creates an HTML report of all implemented security checks.
+
+This report provides a user-friendly overview of the static security checks 
+currently supported by Python Code Audit. It is intended to make it easier to review 
+the available validations without digging through the codebase.
+
+The generated HTML includes:
+- A table of all implemented checks
+- The number of validations
+- The version of Python Code Audit (codeaudit) used
+- A disclaimer about version-specific reporting
+
+The report is saved to the specified filename and is formatted to be 
+embeddable in larger multi-report documents.
+
+Help me continue developing Python Code Audit as free and open-source software.
+Join the community to contribute to the most complete, local first , Python Security Static scanner.
+Help!!  Join the journey, check: https://github.com/nocomplexity/codeaudit#contributing 
+
+
+Parameters:
+    filename (str): The output HTML filename. Defaults to 'codeaudit_checks.html'.
+str(object='') -> str
+str(bytes_or_buffer[, encoding[, errors]]) -> str
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.__str__() (if defined)
+or repr(object).
+encoding defaults to 'utf-8'.
+errors defaults to 'strict'.
+```
+## codeaudit version
+```text
+Prints the module version. Or use codeaudit [-v] [--v] [-version] or [--version].str(object='') -> str
+str(bytes_or_buffer[, encoding[, errors]]) -> str
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.__str__() (if defined)
+or repr(object).
+encoding defaults to 'utf-8'.
+errors defaults to 'strict'.
+```

{codeaudit-1.4.0 → codeaudit-1.4.2}/docs/codeauditoverview.md

@@ -1,12 +1,23 @@
 
 # Command `codeaudit overview`
 
-The command:
 
+
+Use this command to generate a quick security relevant assessment of a Python project or package. It provides an overview of important security metrics for the project.
+
+Usage
+```Bash
+codeaudit overview <package-path|package-name> [report-name.html]
 ```
-codeaudit overview
-```
-is created to give a quick insights in possible security concerns.
+
+Arguments:
+* `<package-path|package-name>` (Required)
+Specify either a local directory containing Python files or the name of a Python package hosted on PyPI.org.
+
+* `[report-name.html]` (Optional)
+The filename for the generated security report. If omitted, the tool will use a default filename. If you provide a custom name, ensure it ends with the `.html` extension.
+
+
 
 For every Python file the following **security** relevant statistics are determined: