codeaudit 1.4.1__py3-none-any.whl → 1.4.2__py3-none-any.whl

codeaudit/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Maikel Mardjan <mike@bm-support.org>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
-__version__ = "1.4.1"
+__version__ = "1.4.2"

codeaudit/api_interfaces.py

@@ -18,7 +18,7 @@ from codeaudit.filehelpfunctions import get_filename_from_path , collect_python_
 from codeaudit.security_checks import perform_validations , ast_security_checks
 from codeaudit.totals import overview_per_file , get_statistics , overview_count , total_modules
 from codeaudit.checkmodules import get_all_modules , get_imported_modules_by_file , get_standard_library_modules , check_module_vulnerability
-
+from codeaudit.pypi_package_scan import get_pypi_download_info , get_package_source
 
 from pathlib import Path
 import json
@@ -35,10 +35,63 @@ def version():
     return {"name" : "Python_Code_Audit",
              "version" : ca_version}
 
-
 def filescan(input_path):
-    """Scans a Python file or directory and returns result as JSON"""    
-    output ={}
+    """
+    Scan a Python source file, a local directory, or a **PyPI package** from PyPI.org for
+    security weaknesses and return the results as a JSON-serializable
+    dictionary.
+
+    This API function works on:
+
+    - **Local directory**: Recursively scans all supported Python files in the
+      directory.
+    - **Single Python file**: Scans the file if it exists and can be parsed
+      into an AST.
+    - **PyPI package** on PyPI.org: Downloads the
+      source distribution from PyPI, scans it, and cleans up temporary files.
+
+    The returned output always includes Python Code Audit version information and a
+    generation timestamp. For consistency, single-file scans are normalized
+    to match the structure of directory/package scans.
+
+    **Note:**
+    The filescan command does NOT include all directories. This is done on purpose!
+    The following directories are skipped by default:
+
+    - `/docs`
+    - `/docker`
+    - `/dist`
+    - `/tests`
+    - all directories that start with . (dot) or _ (underscore) 
+     
+    But you can easily change this if needed!
+
+    Args:
+        input_path (str): One of the following:
+            - Path to a local directory containing Python code.
+            - Path to a single ``.py`` file.
+            - Name of a package available on PyPI.
+
+    Returns:
+        dict: A JSON-serializable dictionary containing scan results and
+        metadata. The structure varies slightly depending on the scan type,
+        but always includes:
+            - Version information from ``version()``.
+            - ``generated_on`` timestamp (``YYYY-MM-DD HH:MM``).
+            - Package or file-level security findings.
+
+        If the input cannot be interpreted as a valid directory, Python file,
+        or PyPI package, a dictionary with an ``"Error"`` key is returned.
+
+    Raises:
+        None explicitly. Any unexpected exceptions are allowed to propagate
+        unless handled by downstream callers.
+
+    Example:
+        >>> result = filescan("example_package")
+        >>> result["package_name"]
+        
+    """
     file_output = {}
     file_path = Path(input_path)
     ca_version_info = version()
@@ -46,35 +99,37 @@ def filescan(input_path):
     timestamp_str = now.strftime("%Y-%m-%d %H:%M")
     output = ca_version_info | {"generated_on" : timestamp_str}    
     # Check if the input is a valid directory or a single valid Python file
-    if file_path.is_dir():
-        files_to_check = collect_python_source_files(input_path)        
-        if len(files_to_check) > 1:
-            modules_discovered = get_all_modules(input_path) #all modules for the package aka directory
-            name_of_package = get_filename_from_path(input_path)
-            package_overview = get_overview(input_path)
-            output |= {"package_name" : name_of_package ,
-                    "statistics_overview" : package_overview ,
-                    "module_overview" : modules_discovered }        
-            for i,file in enumerate(files_to_check):            
-                file_information = overview_per_file(file)
-                module_information = get_modules(file) # modules per file            
-                scan_output = _codeaudit_scan(file)
-                file_output[i] = file_information | module_information | scan_output
-            output |= { "file_security_info" : file_output}
-            return output
-        else:
-            output_msg = f'Directory path {input_path} contains no Python files.'
-            return {"Error" : output_msg}
+    if file_path.is_dir(): #local directory scan
+        package_name = get_filename_from_path(input_path)
+        output |= {"package_name": package_name}
+        scan_output = _codeaudit_directory_scan(input_path)
+        output |= scan_output
+        return output            
     elif file_path.suffix.lower() == ".py" and file_path.is_file() and is_ast_parsable(input_path):   #check on parseable single Python file   
-        #do a file check                        
+        # do a file check
         file_information = overview_per_file(input_path) 
         module_information = get_modules(input_path) # modules per file
         scan_output = _codeaudit_scan(input_path)                
-        file_output[0] = file_information | module_information | scan_output #there is only 1 file , so index 0 equals as for package to make functionality that use the output that works on the dict or json can equal for a package or a single file!
+        file_output["0"] = file_information | module_information | scan_output #there is only 1 file , so index 0 equals as for package to make functionality that use the output that works on the dict or json can equal for a package or a single file!
         output |= { "file_security_info" : file_output}
         return output
+    elif (pypi_data := get_pypi_download_info(input_path)):    
+        package_name = input_path #The variable input_path is now equal to the package name        
+        url = pypi_data['download_url']
+        release = pypi_data['release']
+        if url is not None:
+            src_dir, tmp_handle = get_package_source(url)            
+            output |= {"package_name": package_name,
+                       "package_release": release}
+            try:
+                scan_output = _codeaudit_directory_scan(src_dir)
+                output |= scan_output
+            finally:
+                # Cleaning up temp directory
+                tmp_handle.cleanup()  # deletes everything from temp directory
+            return output
     else:
-        #Its not a directory nor a valid Python file:
+        # Its not a directory nor a valid Python file:
         return {"Error" : "File is not a *.py file, does not exist or is not a valid directory path towards a Python package."}
 
 def _codeaudit_scan(filename):
@@ -90,6 +145,30 @@ def _codeaudit_scan(filename):
               "sast_result": sast_result}    
     return output
 
+def _codeaudit_directory_scan(input_path):
+    """Performs a scan on a local directory
+    Function is also used with scanning directory PyPI.org packages, since in that case a tmp directory is used
+    """
+    output ={}
+    file_output = {}
+    files_to_check = collect_python_source_files(input_path)    
+    if len(files_to_check) > 1:
+        modules_discovered = get_all_modules(input_path) #all modules for the package aka directory        
+        package_overview = get_overview(input_path)
+        output |= {"statistics_overview" : package_overview ,
+                   "module_overview" : modules_discovered }        
+        for i,file in enumerate(files_to_check):
+            file_information = overview_per_file(file)
+            module_information = get_modules(file) # modules per file            
+            scan_output = _codeaudit_scan(file)
+            file_output[i] = file_information | module_information | scan_output
+        output |= { "file_security_info" : file_output}
+        return output
+    else:
+        output_msg = f'Directory path {input_path} contains no Python files.'
+        return {"Error" : output_msg}
+
+
 def save_to_json(sast_result, filename="codeaudit_output.json"):
     """
     Save a SAST result (dict or serializable object) to a JSON file.
@@ -208,13 +287,39 @@ def get_overview(input_path):
         return {"Error" : "File is not a *.py file, does not exist or is not a valid directory path to a Python package."}
 
 def get_default_validations():
-    """Retrieves the implemented default security validations
-    Args:
-        none
+    """Retrieve the default implemented security validations.
+
+    This function collects the built-in Static Application Security Testing (SAST)
+    validations applied to standard Python modules. It retrieves the validation
+    definitions, converts them into a serializable format, and enriches the result
+    with generation metadata.
+
+    The returned structure is intended to be consumed by reporting, API, or
+    documentation layers.
 
     Returns:
-        dict: Overview of implemented security SAST validation on Standard Python modules. Including vital help text.
-    """    
+        dict: A dictionary containing generation metadata and a list of security
+        validations. The dictionary has the following structure:
+
+        {
+            "<metadata_key>": <metadata_value>,
+            ...,
+            "validations": [
+                {
+                    "<field>": <value>,
+                    ...
+                },
+                ...
+            ]
+        }
+
+    
+    **Notes**:
+    
+        - Requires Python 3.9 or later due to use of the dictionary union operator (`|`).
+        - The `validations` list is derived from a pandas DataFrame using
+          `to_dict(orient="records")`.
+    """
     df = ast_security_checks()
     result = df.to_dict(orient="records")    
     output = _generation_info() | {"validations" : result}
@@ -255,15 +360,16 @@ def get_psl_modules():
     return output
 
 def get_module_vulnerability_info(module):
-    """Retrieves vulnerability information for external modules using the OSV Database
+    """
+    Retrieves vulnerability information for an external module using the OSV Database.
+
     Args:
-        input: module name
-    
+        module (str): Name of the module to query.
+
     Returns:
-        dict: Result of OSV query 
-    """
+        dict: Generation metadata combined with OSV vulnerability results.
+    """    
     vuln_info = check_module_vulnerability(module)
     key_string = f'{module}_vulnerability_info'
     output = _generation_info() | { key_string : vuln_info}
     return output
-

codeaudit/codeaudit.py

@@ -45,29 +45,32 @@ def display_help():
         docstring = function.__doc__.strip().split('\n')[0] or ""  
         summary = docstring.split("\n", 1)[0]
         print(f"  {command:<20} {summary}")        
-    print("\nUse the Codeaudit documentation to check the security of Python programs and make your Python programs more secure!\nCheck https://simplifysecurity.nocomplexity.com/ \n")
-
+    print("\nUse 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/\n")
 
 def main():
+    if "-?" in sys.argv:      # Normalize help flags BEFORE Fire sees them: fire module treats anything starting with - as a flag/value, not as a help alias.
+        sys.argv[sys.argv.index("-?")] = "--help"
+    if "-help" in sys.argv:      # Normalize help flags BEFORE Fire sees them
+        sys.argv[sys.argv.index("-help")] = "--help"        
     if len(sys.argv) > 1 and sys.argv[1] in ("-v", "--v", "--version", "-version"):
         display_version()
-    elif len(sys.argv) > 1 and sys.argv[1] in ("-help", "-?", "--help", "-h"):
+    elif len(sys.argv) > 1 and sys.argv[1] in ("-help", "--help", "-h"):
         display_help()
     elif len(sys.argv) == 1:
         display_help()
     else:
         fire.Fire(
             {
-                "overview": overview_report,               
+                "overview": overview_report,
                 "modulescan": report_module_information,
-                "filescan" : scan_report,                
-                "checks" : report_implemented_tests,
-                "version" : display_version,
-                "-help": display_help,
+                "filescan": scan_report,
+                "checks": report_implemented_tests,
+                "version": display_version,
             }
         )
 
 
+
 if __name__ == "__main__":
     main()
 

codeaudit/reporting.py

@@ -41,12 +41,48 @@ SIMPLE_CSS_FILE = files('codeaudit') / 'simple.css'
 DEFAULT_OUTPUT_FILE = 'codeaudit-report.html'
 
 def overview_report(directory, filename=DEFAULT_OUTPUT_FILE):
-    """Reports complexity and security statistics of a Python project or package on PyPI.org.
+    """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.
     
-    Parameters:
-        directory (str): Path to the directory to scan.
-        filename (str): Output filename for the HTML report.
-    """    
+    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.    
+    """
     clean_up = False
     if os.path.exists(directory):
         # Check if the path is actually a directory
@@ -128,21 +164,51 @@ def overview_report(directory, filename=DEFAULT_OUTPUT_FILE):
         
         
 
-def scan_report(input_path , filename=DEFAULT_OUTPUT_FILE):
-    """Scans Python code or packages on PyPI.org for security weaknesses.
-        
-    This function performs security validations on the specified file or directory, 
-    formats the results into an HTML report, and writes the output to an HTML file. 
-    
-    You can specify the name of the outputfile and directory for the generated HTML report. Make sure you chose the extension `.html` since the output file is a static html file.
+def scan_report(input_path, filename=DEFAULT_OUTPUT_FILE):
+    """Scans Python source code or PyPI packages for security weaknesses.
 
-    Parameters:
-        file_to_scan (str)      : The full path to the Python source file to be scanned.
-        filename (str, optional): The name of the HTML file to save the report to.
-                                  Defaults to `DEFAULT_OUTPUT_FILE`.
+    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 - A HTML report is written as output
+        None. The function writes a static HTML security report to disk.
+
+    Raises:
+        None explicitly. Errors and invalid inputs are reported to stdout.    
     """
     # Check if the input is a valid directory or a single valid Python file 
     # In case no local file or directory is found, check if the givin input is pypi package name
@@ -295,9 +361,38 @@ def directory_scan_report(directory_to_scan , filename=DEFAULT_OUTPUT_FILE , pac
     html += DISCLAIMER_TEXT
     create_htmlfile(html,filename)  
 
+def report_module_information(inputfile, reportname=DEFAULT_OUTPUT_FILE):
+    """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.
 
-def report_module_information(inputfile,reportname=DEFAULT_OUTPUT_FILE):
-    """Reports module vulnerability information.""" 
+    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.
+    
+    """
     source = read_in_source_file(inputfile)
     used_modules = get_imported_modules(source)
     # Initial call to print 0% progress
@@ -444,18 +539,23 @@ def report_implemented_tests(filename=DEFAULT_OUTPUT_FILE):
     Creates an HTML report of all implemented security checks.
 
     This report provides a user-friendly overview of the static security checks 
-    currently supported by codeaudit. It is intended to make it easier to review 
+    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 codeaudit used
+    - 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'.
     """    

{codeaudit-1.4.1.dist-info → codeaudit-1.4.2.dist-info}/METADATA

@@ -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.dist-info → codeaudit-1.4.2.dist-info}/RECORD

@@ -1,22 +1,22 @@
-codeaudit/__about__.py,sha256=51z3UeWN1de8e5FUgOaRRqaJqD09d4dlh5EGubUfyqg,144
+codeaudit/__about__.py,sha256=ZFZWLshIXTzzWzLpG6F82-bf1qgOivq-oT9i9-lECak,144
 codeaudit/__init__.py,sha256=YGs6qU0BVHPGtXCS-vfBDLO4TOfJDLTWMgaFDTmi_Iw,157
 codeaudit/altairplots.py,sha256=gBXN1_wxUmjzTNizvzbOeCKvUxpClGPdZmK7ICK1x68,4531
-codeaudit/api_interfaces.py,sha256=nnPhVPmodb-2MYCSiToT87uYZypMoX5oKg6WmLCjdiw,11336
+codeaudit/api_interfaces.py,sha256=zWJrLDM8b3b2-rN0gCoPdflEFMzKUz3M7PfXtXvDpd4,15358
 codeaudit/api_reporting.py,sha256=W8eutTJ0d-TENbv5cCmAOfu4GEp_RwiQ4XU5FCmfkoI,1736
 codeaudit/checkmodules.py,sha256=aiF34KO-9HZDRgVBtSwVFdeUxT5_Ka5VtmlfgoLgNVs,5582
-codeaudit/codeaudit.py,sha256=SNTgMtwqnK0OQMnozodqW3dYGk0So3zLQOlIjDC0p9k,3454
+codeaudit/codeaudit.py,sha256=g2HzRX6a3fckKUhyRrk6n3-5qNdVYtZRI1gqQ-QNl10,3775
 codeaudit/complexitycheck.py,sha256=A3_a5v-U0YQr80pWQwSVvOsY_eQtqwNkQf9Txr9mNtQ,3722
 codeaudit/filehelpfunctions.py,sha256=tx7HDCyTkZuw8YieXipQXM8iRfrDfIVZyKb7vjmkEFY,4358
 codeaudit/htmlhelpfunctions.py,sha256=-SMsyfF7TRIfJkrUqoJuh7AoG1RVrYFsZfFljoxVHXc,3246
 codeaudit/issuevalidations.py,sha256=-WdaXT_R-P9w0JbQpJ5ngVoVhG9Yee2ri0aH5SoC1Ao,6404
 codeaudit/pypi_package_scan.py,sha256=yxCXrRvjc4r0YsJYHvHJuJTyHC5QZl3sRQp73akCXx8,4723
-codeaudit/reporting.py,sha256=1SeTx897Ofd-upK2cc5dQtJSbGj6t-Nl28tYFFzun4c,26139
+codeaudit/reporting.py,sha256=GXIiq2fzN5vvSDjSTDKsEuR0hfEWybbvid7DYzAjsZg,30029
 codeaudit/security_checks.py,sha256=wEO_A054zXmLccWGREi6cNADa4IgoOPxHsq-Je5iMIY,2167
 codeaudit/simple.css,sha256=7auhDAUwjdluFIyoCskl-Vfh503prXKqftQrmo0-e_g,3565
 codeaudit/totals.py,sha256=b6OkzcMdqGKPwuGBKrwAeCxBOJxHa5FHauGWnEb-6zM,6387
 codeaudit/data/sastchecks.csv,sha256=fIcyZgymCtAluPta9fTEk6a9DJ2AGJczZYRPUIQuSag,9738
-codeaudit-1.4.1.dist-info/METADATA,sha256=ga885RNu6CR7MmFWzP6vKdVnLjGy5EzyVZNLBAbGvXI,7568
-codeaudit-1.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-codeaudit-1.4.1.dist-info/entry_points.txt,sha256=7w6I8zii62nJHIIF30CRP5g1z8enMqF1pZEDdlw4HcQ,55
-codeaudit-1.4.1.dist-info/licenses/LICENSE.txt,sha256=-5gWaMGKJ54oX8TYP7oeg2zITdTapzyWl9PP0tispuA,34674
-codeaudit-1.4.1.dist-info/RECORD,,
+codeaudit-1.4.2.dist-info/METADATA,sha256=RtT5hL75GoLxYNav079UwxBdpMkLMfbfID-HX6Ijx_E,7628
+codeaudit-1.4.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+codeaudit-1.4.2.dist-info/entry_points.txt,sha256=7w6I8zii62nJHIIF30CRP5g1z8enMqF1pZEDdlw4HcQ,55
+codeaudit-1.4.2.dist-info/licenses/LICENSE.txt,sha256=-5gWaMGKJ54oX8TYP7oeg2zITdTapzyWl9PP0tispuA,34674
+codeaudit-1.4.2.dist-info/RECORD,,