codeaudit 1.4.0__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.0"
+__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

@@ -36,8 +36,8 @@ def display_help():
     print(codeaudit_ascii_art)
     print("Python Code Audit - A modern Python security source code analyzer based on distrust.\n")
     print("Commands to evaluate Python source code:")
-    print('Usage: codeaudit COMMAND [PATH or FILE]  [OUTPUTFILE] \n')
-    print('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.\n')
+    print('Usage: codeaudit COMMAND <directory|package>  [report.html] \n')
+    print('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.\n')
     print('Commands:')
     commands = ["overview", "filescan", "modulescan",  "checks","version"]  # commands on CLI
     functions = [overview_report, scan_report, report_module_information, report_implemented_tests,display_version]  # Related functions relevant for help
@@ -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/pypi_package_scan.py

@@ -51,39 +51,38 @@ def get_pypi_download_info(package_name):
     """Retrieves the sdist download URL
     Using the PyPI JSON API to get the sdist download URL (https://docs.pypi.org/api/json/)
     Note JSON API result is a nested dict with all release info published, so finding the correct sdist download URL needs logic.
-    """
-    if get_pypi_package_info(package_name) :
-        data = get_pypi_package_info(package_name)   
-        releases_dict = data['releases']
-        # Convert the key-value pairs (items) into a list and get the last one
-        last_item = list(releases_dict.items())[-1] #last_item is a Python tuple
-        sdist_download_url = find_download_url(last_item,'source') # We want the download URL of the source, so *.tar.gz file
-        release_info = last_item[0] 
-        pypi_package_info= { "download_url" : sdist_download_url ,
-                            "release" : release_info}
-        return pypi_package_info
-    else:
-        #package does not exist
-        return False
-
-def find_download_url(data, source):
-    """
-    Given the PyPI release tuple and a python_version string,
-    return the URL of the first matching item.
     """    
-    items = data[1] # Access the list of items directly via index 1 , data is a tuple    
-
-    for item in items:
-        if item.get("python_version") == source:
-            return item.get("url")
+    data = get_pypi_package_info(package_name)    
+    if not data:
+        return False
+    # Get the official "latest" version string from the API metadata
+    latest_version = data.get('info', {}).get('version')
+    if not latest_version:
+        return False
 
-    return None  # if no match found`
+    # Access the files associated with that specific version
+    releases_list = data.get('releases', {}).get(latest_version, [])
+    
+    sdist_download_url = None
+    
+    # Explicitly look for the source distribution (sdist)
+    for file_info in releases_list:
+        if file_info.get('packagetype') == 'sdist':
+            url = file_info.get('url')
+            if url and url.endswith(".tar.gz"): #PEP527 I only extract .tar.gz files, older source formats not supported.
+                sdist_download_url = url
+                break # Found it, stop looking
+
+    return {
+        "download_url": sdist_download_url,
+        "release": latest_version
+    }
 
 
 def get_package_source(url, nocxheaders=NOCX_HEADERS, nocxtimeout=10):
     """Retrieves a package source and extract so SAST scanning can be applied
     Make sure to cleanup the temporary dir!! Using e.g. `tmp_handle.cleanup()`  # deletes everything
-    """
+    """    
     try:
         request = Request(url, headers=nocxheaders or {})
         with urlopen(request, timeout=nocxtimeout) as response:

codeaudit/reporting.py

@@ -41,24 +41,76 @@ SIMPLE_CSS_FILE = files('codeaudit') / 'simple.css'
 DEFAULT_OUTPUT_FILE = 'codeaudit-report.html'
 
 def overview_report(directory, filename=DEFAULT_OUTPUT_FILE):
-    """Reports complexity and statistics for Python files in a project directory.
+    """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.    
     """
-    if not os.path.exists(directory):
-        print(f"ERROR: Directory '{directory}' does not exist.")
-        print(f"This function only works for directories which contains one or more Python source code files (*.py). ")
-        exit(1)
-    if not os.path.isdir(directory):
-        print(f"ERROR: '{directory}' is not a directory (maybe you try to run it for a single file)")
-        print(f"This function only works for directories which contains one or more Python source code files (*.py). ")
-        exit(1)
-    #Check if the directory has Python files
-    if not has_python_files(directory):
-        print(f'Error: Directory path {directory} contains no Python files.')
-        exit(1)
+    clean_up = False
+    if os.path.exists(directory):
+        # Check if the path is actually a directory
+        if not os.path.isdir(directory):
+            print(f"ERROR: '{directory}' is not a directory.")
+            print("This function only works for directories containing Python files (*.py).")
+            exit(1)      
+        # Check if the directory contains any .py files
+        if not has_python_files(directory):
+            print(f"ERROR: Directory '{directory}' contains no Python files.")
+            exit(1)
+    elif get_pypi_download_info(directory):
+        # If local path doesn't exist, try to treat it as a PyPI package
+        print(f"No local directory with name:{directory} found locally. Checking if package exist on PyPI...")  
+        package_name = directory #The variable input_path is now equal to the package name
+        print(f"Package: {package_name} exist on PyPI.org!")        
+        pypi_data = get_pypi_download_info(package_name)
+        url = pypi_data['download_url']
+        release = pypi_data['release']
+        if url is not None:
+            print(f'Creating Python Code Audit overview for package:\n{url}')            
+            src_dir, tmp_handle = get_package_source(url)                    
+            directory = src_dir
+            clean_up = True            
+    else:
+        # Neither a local directory nor a valid PyPI package
+        print(f"ERROR: '{directory}' is not a local directory or a valid PyPI package.")
+        exit(1)    
     result = get_statistics(directory)
     modules = total_modules(directory)    
     df = pd.DataFrame(result)
@@ -66,7 +118,11 @@ def overview_report(directory, filename=DEFAULT_OUTPUT_FILE):
     df['External-Modules'] = modules['External-Modules']
     overview_df = overview_count(df)
     html = '<h1>' + f'Python Code Audit overview report' + '</h1><br>'
-    html += f'<p>Codeaudit overview scan of the directory:<b> {directory}</b></p>' 
+    if clean_up:
+        html += f'<p>Codeaudit overview scan of package:<b> {package_name}</b></p>' 
+        html += f'<p>Version:<b>{release}</b></p>'
+    else:
+        html += f'<p>Codeaudit overview scan of the directory:<b> {directory}</b></p>' 
     html += f'<h2>Summary</h2>'
     html += overview_df.to_html(escape=True,index=False)
     html += '<br><br>'
@@ -83,6 +139,8 @@ def overview_report(directory, filename=DEFAULT_OUTPUT_FILE):
     html += '<br>'
     ## Module overview    
     modules_discovered = get_all_modules(directory)
+    if clean_up:
+        tmp_handle.cleanup() #Clean up tmp directory if overview is created directly from PyPI package
     html += '<details>' 
     html += '<summary>Click to see all discovered modules.</summary>'         
     html+=dict_to_html(modules_discovered)
@@ -106,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 on 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
@@ -146,12 +234,16 @@ def scan_report(input_path , filename=DEFAULT_OUTPUT_FILE):
         pypi_data = get_pypi_download_info(package_name)
         url = pypi_data['download_url']
         release = pypi_data['release']
-        print(url)
-        print(release)
-        src_dir, tmp_handle = get_package_source(url)
-        directory_scan_report(src_dir , filename , package_name, release ) #create scan report for a package or directory
-        # Cleaning up temp directory 
-        tmp_handle.cleanup()  # deletes everything from temp directory                
+        if url is not None:
+            print(url)
+            print(release)
+            src_dir, tmp_handle = get_package_source(url)
+            directory_scan_report(src_dir , filename , package_name, release ) #create scan report for a package or directory
+            # Cleaning up temp directory 
+            tmp_handle.cleanup()  # deletes everything from temp directory
+        else:
+            print(f'Error:A source distribution (sdist in .tar.gz format) for package: {package_name} can not be found or does not exist on PyPi.org.\n')
+            print(f"Make a local git clone of the {package_name} using `git clone` and run `codeaudit filescan <directory-with-src-cloned-of-{package_name}>` to check for weaknesses.")
     else:
         #File is NOT a valid Python file, can not be parsed or directory is invalid.
         print(f"Error: '{input_path}' isn't a valid Python file, directory path to a package or a package on PyPI.org.")
@@ -235,7 +327,8 @@ def directory_scan_report(directory_to_scan , filename=DEFAULT_OUTPUT_FILE , pac
     name_of_package = get_filename_from_path(directory_to_scan)
     if package_name is not None:
         #Use real package name and retrieved release info
-        html += f'<p>Below the result of the Codeaudit scan of the package - Release :<b> {package_name} - {release} </b></p>'
+        html += f'<p>Below the result of the Codeaudit scan of (Package name - Release):</p>'
+        html += f'<p><b> {package_name} - {release} </b></p>'
     else:
         html += f'<p>Below the result of the Codeaudit scan of the directory:<b> {name_of_package}</b></p>' 
     html += f'<p>Total Python files found: <b>{len(files_to_check)}</b></p>'
@@ -262,13 +355,44 @@ def directory_scan_report(directory_to_scan , filename=DEFAULT_OUTPUT_FILE , pac
     html += '<p>The Python files with no security issues <b>detected</b> by codeaudit are:<p>'        
     html += dict_list_to_html_table(collection_ok_files)     
     html += '<br>'
+    if package_name is not None:
+        html += f'<p><b>Note:</b><i>Since this check is done on a package on PyPI.org, the temporary local directories are deleted. To examine the package in detail, you should download the sources locally and run the command:<code>codeaudit filescan</code> again.</i></p>'
     html += '<p><b>Disclaimer:</b><i>Only Python source files are taken into account for this scan. Sometimes security issues are present in configuration files, like ini,yaml or json files!</i></p>'
     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.
+
+    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.
 
-def report_module_information(inputfile,reportname=DEFAULT_OUTPUT_FILE):
-    """Reports module vulnerability information.""" 
+    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
@@ -415,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.0.dist-info → codeaudit-1.4.2.dist-info}/METADATA

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

@@ -1,22 +1,22 @@
-codeaudit/__about__.py,sha256=-bxUcBaBrbGG65qQWVQjAxsqncjywKoDesQoM0JjIYc,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=yQ7SHx8b3Q9rMu8nCVyyuu3wJr3DlO-BuSIz2ZwJFGM,3426
+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=JxgcCtJaVH9pAQ902gjmzgGGECt71r4gnFhqcZUy3OE,4872
-codeaudit/reporting.py,sha256=eXlslslMgG_4ATFpTEi5wtgwTMOgngAi-38Fg-xaYN4,24299
+codeaudit/pypi_package_scan.py,sha256=yxCXrRvjc4r0YsJYHvHJuJTyHC5QZl3sRQp73akCXx8,4723
+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.0.dist-info/METADATA,sha256=I-dT_-7IdlcdNEinahwY4CN-j6Ty8Q9wlrTbb84dqUk,7505
-codeaudit-1.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-codeaudit-1.4.0.dist-info/entry_points.txt,sha256=7w6I8zii62nJHIIF30CRP5g1z8enMqF1pZEDdlw4HcQ,55
-codeaudit-1.4.0.dist-info/licenses/LICENSE.txt,sha256=-5gWaMGKJ54oX8TYP7oeg2zITdTapzyWl9PP0tispuA,34674
-codeaudit-1.4.0.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,,