codeaudit 1.4.1__tar.gz → 1.4.2__tar.gz

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

@@ -1,9 +1,24 @@
 # 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 command now supports packages hosted directly on PyPI.org.
+* 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

{codeaudit-1.4.1 → 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.1 → codeaudit-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeaudit
-Version: 1.4.1
+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
@@ -106,14 +106,13 @@ 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             Reports complexity and security statistics of a Python project or package on PyPI.org.
-  filescan             Scans Python code or packages on PyPI.org for security weaknesses.
-  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

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

@@ -78,14 +78,13 @@ 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             Reports complexity and security statistics of a Python project or package on PyPI.org.
-  filescan             Scans Python code or packages on PyPI.org for security weaknesses.
-  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

{codeaudit-1.4.1 → 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.1 → 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'.
+```