codeaudit 1.4.1__tar.gz → 1.5.0__tar.gz

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

@@ -1,9 +1,47 @@
 # Change Log
 
+## Version 1.5.0: 
+Added:
+
+* External Egress Risk Detection: New functionality to identify potential API keys or logic used for connecting to remote services. Reports now include the specific line and "keyword" associated with the identified risk.
+*Note: External Egress Risk Detection is still experimental and in beta status! [Help improve it!](CONTRIBUTE).*
+
+Changed:
+
+* CLI HTML Reporting: Refined the reporting output for single file scans. Users will now see a clear, dedicated line when no security weaknesses are found.
+
+* UI/UX Enhancements: Applied "Look & Feel" improvements across all HTML report templates for better readability and aesthetics.
+
+* General CLI Polish: Improved various text strings throughout the Command Line Interface for better clarity.
+
+Fixed:
+
+* Error Messaging: Improved the descriptiveness and clarity of CLI error messages to assist in troubleshooting.
+
+Documentation:
+
+* Report Naming Conventions: Improved the titles of HTML reports. This ensures that when a user saves a report as a PDF via a browser, the default filename is more descriptive and professional.
+
+
+## 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.5.0}/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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeaudit
-Version: 1.4.1
+Version: 1.5.0
 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
@@ -64,6 +64,10 @@ Python Code Audit has the following features:
 
 * **Inline Issue Reporting**: Shows potential security issues with line numbers and code snippets.
 
+
+* **External Egress Detection**: Identifies embedded API keys and logic that enables communication with remote services, helping uncover hidden data exfiltration paths.
+
+
 * **HTML Reports**: All output is saved in simple, static HTML reports viewable in any browser.
 
 
@@ -100,20 +104,20 @@ 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 <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           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].
 
-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.5.0}/README.md

@@ -36,6 +36,10 @@ Python Code Audit has the following features:
 
 * **Inline Issue Reporting**: Shows potential security issues with line numbers and code snippets.
 
+
+* **External Egress Detection**: Identifies embedded API keys and logic that enables communication with remote services, helping uncover hidden data exfiltration paths.
+
+
 * **HTML Reports**: All output is saved in simple, static HTML reports viewable in any browser.
 
 
@@ -72,20 +76,20 @@ 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 <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           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].
 
-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.5.0}/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.5.0}/docs/_toc.yml

@@ -2,23 +2,29 @@ format: jb-book
 root: intro
 
 parts:
-- caption: Quick Start
+- caption: Getting Started
   chapters:    
   - file: features
+  - file: installation
   - file: howtoscan
+  - file: whatissast
+  - file: whysast
+  
+
+
+- caption: User Guide
+  chapters:
   - file: userguide
     sections:
     - file: codeauditoverview    
     - file: filescan
     - file: modulescan
     - file: codeauditchecks  
-  - file: whatissast
-  - file: whysast
   - file: issues
-  
-
-- caption: Security Checks
-  chapters:
+  - file: securecoding
+  - file: complexitycheck
+  - file: warnings
+  - file: handling_errors
   - file: implementedvalidations
   - file: checksinformation
     sections:
@@ -47,17 +53,14 @@ parts:
     - file: checks/xml_check
     - file: checks/zipfile_check
     - file: checks/shutil_check
-  - file: securecoding
+ 
 
 - caption: Architecture 
   chapters:     
   #- file: astlines
   # - file: astlines2
   - file: makeitbetter
-  - file: project_philosophy
-  - file: complexitycheck
-  - file: warnings
-  - file: handling_errors
+  - file: project_philosophy  
   - file: codeauditcommands  
   - file: changelog
   
@@ -67,6 +70,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.5.0/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.1 → codeaudit-1.5.0}/docs/checksinformation.md

@@ -1,4 +1,4 @@
-# Information on checks
+# Detections & Mitigations
 
 **Python Code Audit** has many implemented security checks based on possible security threats when using Python Standard Library (PSL) calls.
 

codeaudit-1.5.0/docs/codeauditcommands.md

@@ -0,0 +1,240 @@
+% THIS FILE IS GENERATED! - Use CLIcommands.ipynb to make it better!
+# Commands Overview
+Python Code Audit commands for: version: 1.5.0
+```
+----------------------------------------------------
+ _                    __             _             
+|_) \/_|_|_  _ __    /   _  _| _    |_|    _| 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           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].
+
+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
+
+So:
+codeaudit overview <package-name|directory> [reportname.html]
+
+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
+
+Generate a report on known vulnerabilities in Python modules and packages.
+
+This function analyzes a single Python file to identify imported
+external modules and checks those modules against the OSV vulnerability
+database. The collected results are written to a static HTML report.
+
+If the input refers to a valid PyPI package name instead of a local Python
+file, the function generates a vulnerability report directly for that
+package.
+
+While processing modules, progress information is printed to standard
+output.
+
+Example:
+    Generate a module vulnerability report for a Python file::
+
+        codeaudit modulescan <pythonfile>|<package> [yourreportname.html]
+
+        codeaudit modulescan mypythonfile.py
+
+Args:
+    inputfile (str): Path to a Python source file (*.py) to analyze, or the
+        name of a package available on PyPI.
+    reportname (str, optional): Name (and optional path) of the HTML file to
+        write the 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:
+    SystemExit: If the input is not a valid Python file or a valid PyPI
+        package. File parsing and I/O errors are reported via standard
+        output before exiting.
+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
+
+codeaudit filescan <pythonfile|package-name|directory> [reportname.html]
+
+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'.
+```