codeaudit 1.4.1__py3-none-any.whl → 1.5.0__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.5.0"

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/data/secretslist.txt

@@ -0,0 +1,135 @@
+
+_KEY
+_passwd
+_PASSWORD
+access_key
+access_key_id
+ACCESS_SECRET
+ACCESS_TOKEN
+AccountKey
+AI21_API_KEY
+ALIBABA_CLOUD_ACCESS_KEY_ID
+ALIBABA_CLOUD_ACCESS_KEY_SECRET
+ANTHROPIC_API_KEY
+api_key
+API_TOKEN
+ApiKey
+ApiSecret
+APP_KEY
+APP_SECRET
+AUTH
+auth_key
+AUTH_SECRET
+auth_token
+AUTH_TOKEN
+Authorization
+AWS_ACCESS_KEY_ID
+aws_account_id
+aws_secret_access_key
+AWS_SECRET_ACCESS_KEY
+aws_session_token
+AWS_SESSION_TOKEN
+AZURE_OPENAI_API_KEY
+AZURE_OPENAI_API_VERSION
+AZURE_OPENAI_ENDPOINT
+AzureStorageKey
+BAIDU_API_KEY
+BAIDU_SECRET_KEY
+BASIC_AUTH
+BEARER
+BEARER_TOKEN
+BEDROCK_REGION
+CLIENT_ID
+client_key
+CLIENT_SECRET
+ClientSecret
+COHERE_API_KEY
+CONNECTION_STRING
+credential
+credentials
+CREDENTIALS_JSON
+creds
+CSRF_TOKEN
+DASHSCOPE_API_KEY
+DEEPSEEK_API_KEY
+DEPLOY_KEY
+encryptedPassword
+ENCRYPTION_SECRET
+EncryptionKey
+FERNET_KEY
+FIREWORKS_API_KEY
+GCP_SERVICE_ACCOUNT_KEY
+GEMINI_API_KEY
+get_api_token
+get_secret
+get_token
+GITHUB_TOKEN
+GOOGLE_API_KEY
+GOOGLE_API_KEY
+HMAC_KEY
+HUGGINGFACE_API_TOKEN
+IBM_WATSONX_API_KEY
+IBM_WATSONX_PROJECT_ID
+ID_TOKEN
+INTEGRATION_KEY
+JWT_ACCESS_TOKEN
+JWT_ALGORITHM
+JWT_AUDIENCE
+JWT_ISSUER
+JWT_PRIVATE_KEY
+JWT_PUBLIC_KEY
+JWT_REFRESH_TOKEN
+JWT_SECRET
+JWT_SECRET_KEY
+JWT_SIGNING_KEY
+JWT_TOKEN
+KEYFILE
+KUBE_TOKEN
+MASTER_KEY
+MISTRAL_API_KEY
+MLAB_PASS
+MOONSHOT_API_KEY
+NetworkCredential
+NVIDIA_API_KEY
+OAUTH_TOKEN
+OLLAMA_API_BASE
+OPENAI_API_KEY
+OPENROUTER_API_KEY
+OTEL_EXPORTER
+PASSPHRASE
+password
+POSTGRES_PASSWORD
+PPLX_API_KEY
+PRIVATE_KEY
+PRIVATE_TOKEN
+REDIS_PASSWORD
+REFRESH_TOKEN
+REPLICATE_API_TOKEN
+ROOT_PASSWORD
+RSA_PRIVATE_KEY
+SAS_TOKEN
+secret
+secret_key
+secret_key_base
+SECRET_TOKEN
+SERVICE_ACCOUNT_KEY
+SESSION_KEY
+SIGNING_KEY
+SILICONFLOW_API_KEY
+SLACK_TOKEN
+SMTP_PASSWORD
+SSH_KEY
+static_key
+STRIPE_API_KEY
+SYSTEM_PASSWORD
+TENCENT_HUNYUAN_API_KEY
+TLS_PRIVATE_KEY
+TOGETHER_API_KEY
+TOKEN
+VAULT_TOKEN
+WEBHOOK_SECRET
+WEBHOOK_TOKEN
+X_API_KEY
+XAI_API_KEY
+YI_API_KEY
+ZHIPUAI_API_KEY

codeaudit/filehelpfunctions.py

@@ -24,7 +24,7 @@ def read_in_source_file(file_path):
 
     if file_path.is_dir():
         print(
-            "Error: The given path is a directory.\nUse 'codeaudit directoryscan' to audit all Python files in a directory.\nThe 'codeaudit modulescan' command works per file only, not on a directory.\nUse codeaudit -h for help"
+            "Error: The given path is a directory.\nUse 'codeaudit filescan' to security audit Python files in a directory or PyPI package.\nThe 'codeaudit modulescan' command works per file only, not on a directory.\nUse codeaudit -h for help"
         )
         sys.exit(1)