codeaudit 1.4.2__tar.gz → 1.5.0__tar.gz

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

@@ -1,5 +1,28 @@
 # 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:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeaudit
-Version: 1.4.2
+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,6 +104,7 @@ 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] 
 
@@ -108,7 +113,7 @@ Depending on the command, you must specify a local directory, a Python file, or
 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.
+  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].
 

{codeaudit-1.4.2 → 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,6 +76,7 @@ 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] 
 
@@ -80,7 +85,7 @@ Depending on the command, you must specify a local directory, a Python file, or
 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.
+  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].
 

{codeaudit-1.4.2 → 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
   

{codeaudit-1.4.2 → 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.4.2 → codeaudit-1.5.0}/docs/codeauditcommands.md

@@ -1,6 +1,6 @@
 % THIS FILE IS GENERATED! - Use CLIcommands.ipynb to make it better!
 # Commands Overview
-Python Code Audit commands for: version: 1.4.2
+Python Code Audit commands for: version: 1.5.0
 ```
 ----------------------------------------------------
  _                    __             _             
@@ -18,7 +18,7 @@ Depending on the command, you must specify a local directory, a Python file, or
 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.
+  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].
 
@@ -35,6 +35,9 @@ 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.
@@ -81,36 +84,41 @@ 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.
+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.
 
-For each detected external module, the report indicates whether known
-vulnerability information exists and, if available, includes detailed
-vulnerability data.
+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.
 
-Progress information is printed to stdout while processing modules.
+While processing modules, progress information is printed to standard
+output.
 
 Example:
     Generate a module vulnerability report for a Python file::
 
-        codeaudit modulescan mypythonfile.py 
+        codeaudit modulescan <pythonfile>|<package> [yourreportname.html]
+
+        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``.
+    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.
+    None: The function writes a static HTML report to disk.
 
 Raises:
-    None explicitly. File reading errors or invalid input are reported
-    via standard output.
-
+    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
 
@@ -133,6 +141,8 @@ given input, which can be:
 - 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.

{codeaudit-1.4.2 → codeaudit-1.5.0}/docs/examples/demoscan.json

@@ -1,7 +1,7 @@
 {
   "name": "Python_Code_Audit",
-  "version": "1.4.2",
-  "generated_on": "2026-01-10 10:50",
+  "version": "1.5.0",
+  "generated_on": "2026-01-16 11:23",
   "file_security_info": {
     "0": {
       "FileName": "demofile.py",

codeaudit-1.5.0/docs/features.md

@@ -0,0 +1,88 @@
+# Features
+
+
+**Python Code Audit** is a modern Python **security** source code analysis tool built on a *zero-trust* mindset. It focuses on identifying security risks, hidden behaviors, and trust boundaries in Python code—without executing it.
+
+:::{admonition} Key Features of Python Code Audit
+:class: tip
+
+* **Vulnerability Detection**  
+  Detects potential security issues in Python source files. This is essential for validating trust in third-party modules and supporting security research.
+
++++
+
+* **External Egress Detection**  
+  Identifies embedded API keys and logic that enables communication with remote services, helping uncover hidden data exfiltration paths.
+
++++
+
+* **Complexity & Security-Relevant Statistics**  
+  Reports code metrics relevant to security analysis, including a fast and lightweight
+  [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) calculation using the Python AST.
+
++++
+
+* **Module Usage & Known Vulnerabilities**  
+  Detects imported modules and correlates them with known security vulnerabilities.
+
++++
+
+* **Inline Issue Reporting**  
+  Highlights potential security issues directly in context, including line numbers and relevant code snippets.
+
++++
+
+* **Static HTML Reports**  
+  Generates clean, self-contained HTML reports that can be viewed in any modern web browser.
+
+:::
+
+## In-Depth Capability Overview
+
+Python Code Audit provides a comprehensive set of features designed to enhance Python code security analysis:
+
+### Code Complexity & Statistics
+
+Analyzes individual Python files or entire packages *prior to execution* and collects security relevant metrics, including:
+
+- Number of files
+- Total lines of code
+- AST node count
+- Imported modules
+- Defined functions
+- Defined classes
+- Comment lines
+
+Statistics are reported per file, along with an aggregated summary for the entire package or directory.
+
+### Module Usage Reporting
+
+Identifies and lists all modules imported by each Python file, providing visibility into dependencies and potential attack surfaces.
+
+### Module Security Intelligence
+
+Surfaces known security information and vulnerabilities associated with the detected modules.
+
+### Per-File Vulnerability Detection
+
+Detects potential security weaknesses within individual Python files and reports:
+- Affected line numbers
+- Relevant code snippets
+- Contextual details to aid investigation
+
+### External Egress Detection
+
+Scans for:
+- Over 135 known API key formats
+- Common networking and remote-connection patterns
+
+This capability helps determine whether a Python file or library can transmit data to external services.
+
+### Directory-Wide (Package-Level) Scanning
+
+Performs vulnerability detection across all Python files in a directory or package, making it ideal for assessing the security posture of Python libraries and distributions.
+
+### APIs for Integration
+
+The Python Code Audit APIs empower you to build your own Python security tools or create seamless integrations you need! 
+So create your own security dashboards, CICD integrations or custom integrations needed for your security management system. Powerfull but simple APIs are provided.

{codeaudit-1.4.2 → codeaudit-1.5.0}/docs/filescan.md

@@ -11,13 +11,13 @@ See section [validations](checksinformation) for all security checks implemented
 To use the `codescan filescan` feature type in the console:
 
 ```
-codeaudit filescan <INPUTFILE>  [OUTPUTFILE]
+codeaudit filescan <pythonfile|package-name|directory>  [OUTPUTFILE]
 ```
 
-The `<INPUTFILE>` is mandatory. **Python Code Audit** will create a detailed security scan report. 
+**Python Code Audit** will create a detailed security scan report based on a single Python file, a local directory or a package on PyPI.org
 
 
-**`<INPUTFILE>`** can be:
+So the input for `codeaudit filescan`  can be:
 * A single Python file;
 * A package on PyPI.org: Python Code Audit checks this package on security weakness, so cloning the sources local is not needed!
 * A local directory with Python files, e.g. a local package development environment or a cloned package.

codeaudit-1.5.0/docs/howtoscan.md

@@ -0,0 +1,173 @@
+# How to do a SAST test?
+
+Running a Static Application Security Test (SAST) on Python code is essential for ensuring security. It’s also a straightforward [shift-left practice](https://nocomplexity.com/documents/simplifysecurity/intro.html#)  that takes only a fraction of your time yet can help you avoid serious security incidents.
+
+
+
+Follow these steps to perform a **static application security test (SAST)** on Python projects using **Python Code Audit**.  
+
+
+
+## Install Python Code Audit
+
+[Python Code Audit](https://pypi.org/project/codeaudit/) is an open-source, zero-configuration tool that validates whether your Python code introduces potential security vulnerabilities.  
+
+Install (or update) it with:  
+
+```bash
+pip install -U codeaudit
+```
+
+:::{tip} 
+Even if you already have it installed, it’s recommended to run the command again to ensure you’re using the latest checks and features.  
+:::
+
+
+
+## Chose a Python package that is available on PyPI.org
+
+:::{admonition} Install Python programs only from Trusted Sources.
+:class: note
+This is crucial from a security perspective!
+
+Use only official, managed repositories for installation such as:
+- PyPI.org
+- conda
+- conda-forge
+:::
+
+
+### Do the security sccan
+
+On the command line do:
+```bash
+codeaudit filescanscan <package-name|directory|file> [reportname.html]
+```
+
+You can chose a custom report name. But make sure it ends with `.html` since a the report is a static html file.
+
+Example for a security check on a PyPI library for detecting broken links in markdown files:
+```bash
+codeaudit filescan linkaudit
+```
+
+This gives the output:
+```
+Package: linkaudit exist on PyPI.org!
+Now SAST scanning package from the remote location: https://pypi.org/pypi/linkaudit
+https://files.pythonhosted.org/packages/8a/5a/e9d4ae4b006ac7fb2faf0d3047ee759d8366b85290ddc0e595bbe290d6c5/linkaudit-0.9.7.tar.gz
+0.9.7
+Number of files that are checked for security issues:6
+Progress: |██████████████████████████████████████████████████| 100.0% Complete
+
+=====================================================================
+Code Audit report file created!
+Paste the line below directly into your browser bar:
+	file:///home/securityproject/example/codeaudit-report.html
+
+=====================================================================
+
+```
+
+The report will look like:
+![The report will look like](images/filescan_screenshot_16012026.png)
+
+
+## Generate an Overview Report
+
+Navigate into the cloned repository, then run:  
+
+```bash
+codeaudit overview <package-name|directory> [reportname.html]
+```
+
+This command provides:  
+- Total number of files  
+- Total lines of code  
+- Imported modules  
+- Complexity per file  
+- Overall complexity score  
+
+Example for a security check on a PyPI library for RSS parsing:
+```bash
+codeaudit overview ultrafastrss
+```
+
+This gives the output:
+```
+No local directory with name:ultrafastrss found locally. Checking if package exist on PyPI...
+Package: ultrafastrss exist on PyPI.org!
+Creating Python Code Audit overview for package:
+https://files.pythonhosted.org/packages/c7/45/4f10aaf692e0bc67e8f089a3514804491f3edbacbed2658b191adc3a109b/ultrafastrss-0.9.2.tar.gz
+
+=====================================================================
+Code Audit report file created!
+Paste the line below directly into your browser bar:
+	file:///home/securityproject/example/codeaudit-report.html
+
+=====================================================================
+
+```
+The report will look like:
+![overview report](images/overview_screenshot_16012026.png)
+
+
+:::{tip} 
+📖 More detailed explanations of these metrics can be found in the [Python Code Audit documentation](https://nocomplexity.com/documents/codeaudit/intro.html).  
+:::
+
+
+
+---
+
+## Check for known vulnerabilities in imported libraries
+
+To check for known vulnerabilities in Python modules and packages you can do:
+
+```
+ codeaudit modulescan <pythonfile>|<package> [yourreportname.html]
+ ```
+To check for known vulnerabilities in a local Python file or a package on PyPI.org
+
+Example, to check for known vulnerabilities in imported libraries in the Flair NLP package:
+```bash
+codeaudit modulescan flair
+```
+
+
+The report will look like:
+![overview report](images/modulescan_screenshot_16012026.png)
+
+:::{tip} 
+To analyze this package for potential security weaknesses, run:
+
+`codeaudit filescan <file|package-name>`
+
+**Most real-world vulnerabilities and insecure coding practices are never formally disclosed or assigned a CVE**. As a result, source code analysis provides far greater security insight than relying solely on known vulnerability databases. Scanning the code itself helps uncover hidden risks, unsafe patterns, and trust violations that would otherwise remain undetected.
+
+:::
+
+
+## Review the Security Report
+
+The **Python Code Audit** security scan generates a static **HTML report** in the directory where you ran the command.  
+
+Example output path:  
+
+```
+file:///home/usainbolt/testdir/codeaudit-report.html
+```
+
+- On **Linux**, you can usually click the link directly in the terminal.  
+- On **Windows**, you may need to manually copy and paste the file path into your browser.  
+
+
+
+✅ You now have a detailed static application security test (SAST) report highlighting potential security issues in your Python code. 
+
+
+:::{hint} 
+If you need assistance with solving or want short and clear advice on possible security risks for your context:
+
+Get expert security advice  from one of our [sponsors](sponsors)!
+:::

codeaudit-1.5.0/docs/installation.md

@@ -0,0 +1,24 @@
+# Installation
+
+Python Code Audit is compatible with both Unix-based systems (Linux/macOS) and Windows.
+
+
+To install or upgrade to the latest version, run the following command in your terminal or command prompt:
+
+```bash
+pip install -U codeaudit
+```
+
+Once the installation is complete, you can begin scanning Python Packages immediately. Open a new shell or Command Prompt window and execute any of the Python Code Audit commands to verify the setup.
+
+Example:
+
+```bash
+codeaudit filescan ultrafastrss
+```
+This will scan the `ultrafastrss` package directly from PyPI.org and create a html report.
+
+
+:::{hint} 
+It is recommended to use `pip` for installation. 
+:::

{codeaudit-1.4.2 → codeaudit-1.5.0}/docs/intro.md

@@ -20,7 +20,7 @@
 ^^^
 In the Getting Started section you can find installation instructions and a high-level overview of the main concepts.
 +++
-```{button-ref} userguide
+```{button-ref} installation
 :link-type: ref
 :color: danger
 Quick Start Guide
@@ -32,7 +32,7 @@ Quick Start Guide
 ^^^
 Check out the User Guides for in-depth information on the key concepts of Python Code Audit.
 +++
-```{button-ref} whatissast
+```{button-ref} userguide
 :link-type: ref
 :color: danger
 User Guide
@@ -113,6 +113,11 @@ Are you ready to discover what's lurking in your code?
 
 +++
 
+
+* **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 in used modules.
 
 

{codeaudit-1.4.2 → codeaudit-1.5.0}/docs/makeitbetter.md

@@ -78,6 +78,8 @@ Get in contact with the developers! The most simple way is to report the feature
 :::
 
 
+`Hatch` is used for packaging. By default [`Hatch`](https://hatch.pypa.io/latest/config/build/#reproducible-builds) supports [reproducible builds](https://nocomplexity.com/documents/securityarchitecture/prevention/reproduciblebuilds.html#reproducible-builds).
+
 
 The **Python Code Audit** tool is designed using the [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.