codeaudit 0.9.3__tar.gz → 1.1.0__tar.gz

codeaudit-1.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Change Log
+
+## Version 1.1:What's New
+
+We've released a new version with several key improvements focused on making your security workflow smoother and providing more detailed security information.
+
+* Streamlined Scanning:
+
+The separate `directoryscan` command has been removed. You can now use the versatile `filescan` command to scan both individual files and entire directories. This simplifies the command-line interface and makes the process more intuitive.
+
+* Enhanced Reporting:
+
+We've made minor corrections to the documentation and static HTML reports to improve clarity. Additionally, warning messages are now more descriptive, helping you quickly understand potential issues.
+
+* Improved Vulnerability Data:
+
+You'll now get more detailed information about module vulnerabilities. The tool now includes CVSS scores, a standard metric for rating vulnerability severity, giving you a clearer picture of the risks.
+
+* Behind-the-Scenes Fixes:
+
+We've made a more robust and reliable adjustment to how the tool retrieves file names. This ensures consistency and accuracy during scans. We've also added beta-level API functions, opening up new possibilities for integration.
+
+
+
+## Version 1.0
+
+This release represents a stabilisation of Python Code Audit!
+Main changes in relation to the pre-1.0 versions are:
+* More validations added: Python Code Audit now counts 70 security validations!
+* Documentation updates
+* Improved validation for `builtins`, like `compile`, `exec`,, `eval` that can be obfuscated in code. 
+* Various UI/UX updates. CLI text improved and HTML report text made consistent. 
+* Added test to validate correct working for now and in the future. Also validated working with other SAST tools to make sure core functionality is rock solid or better! Spoiler Python Code Audit is better than most used OSS and commercial SAST tools available today!
+
+
+## Beta Versions (Before 1.0)
+
+All published beta version are stable and verified!
+During the public beta phase input of users and experts is retrieved. 
+This resulted is mainly:
+* More validation
+* Better documentation and
+* UI/UX improvements to make sure Python Code Audit is dead simple to use for non-programmers to validate a Python package.
+

{codeaudit-0.9.3 → codeaudit-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeaudit
-Version: 0.9.3
+Version: 1.1.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
@@ -33,28 +33,28 @@ Description-Content-Type: text/markdown
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10970/badge)](https://www.bestpractices.dev/projects/10970)
 [![PyPI Downloads](https://static.pepy.tech/badge/codeaudit)](https://pepy.tech/projects/codeaudit)
 
-Python Codeaudit - A modern Python source code analyzer based on distrust.
+Python Code Audit - A modern Python source code analyzer based on distrust.
 
-Codeaudit is a tool to find security issues in Python code. This static application security testing (SAST) tool has **great** features to simplify the necessary security tasks and make it fun and easy. 
+Python Code Audit is a tool to find **security issues** in Python code. This static application security testing (SAST) tool has **great** features to simplify the necessary security tasks and make it fun and easy. 
 
-This tool is created for:
-* Anyone who want or must check security risks with Python programs.
-* Anyone who loves to create functionality using Python. So not only professional programs , but also occasional Python programmers or programmers who are used to working with other languages.
-* Anyone who wants an easy way to get insight in possible security risks Python programs.
+This tool is designed for anyone who uses or creates Python programs and wants to understand and mitigate potential security risks.
 
+This tool is created for:
+* Python Users who want to assess the security risks in the Python code they use.
+* Python Developers: Anyone, from professionals to hobbyists, who wants to deliver secure Python code.
+* Security-Conscious Users: People seeking a simple, fast way to gain insight into potential security vulnerabilities within Python packages or files.
 
-> [!WARNING]
-> Python Codeaudit is currently in *beta status*. Consider [contributing](CONTRIBUTING.md) to make Codeaudit the coolest open source Python SAST tool. Codeaudit is currently in a thorough testing phase. Use Python Codeaudit now and contribute to make it better!
+Creating secure software can be challenging. This tool, with its comprehensive [documentation](https://nocomplexity.com/documents/codeaudit/intro.html), acts as your helpful security colleague, making it easier to identify and address vulnerabilities.
 
 ## Features
 
-Python Codeaudit has the following features:
+Python Code Audit has the following features:
 
 * **Vulnerability Detection**: Identifies security vulnerabilities in Python files, essential for package security research.
 
 * **Complexity & Statistics**: Reports security-relevant complexity using a fast, lightweight [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) count via Python's AST.
 
-* **Module Usage & External Vulnerabilities**: Detects used modules and reports vulnerabilities in external ones.
+* **Module Usage & External Vulnerabilities**: Detects used modules and reports known vulnerabilities for used external modules.
 
 * **Inline Issue Reporting**: Shows potential security issues with line numbers and code snippets.
 
@@ -63,7 +63,7 @@ Python Codeaudit has the following features:
 
 
 > [!IMPORTANT]
-> Python Codeaudit uses the Python's Abstract Syntax Tree (AST) to get robust and reliable result. Using the Python AST makes contextual Vulnerability Detection possible and false positive are minimized.
+> Python Code Audit uses the Python's Abstract Syntax Tree (AST) to get robust and reliable result. Using the Python AST makes contextual Vulnerability Detection possible and false positive are minimized.
 
 
 ## Installation
@@ -74,11 +74,11 @@ pip install codeaudit
 
 or use:
 
-```bash
+```console
 pip install -U codeaudit
 ```
 
-If you have installed Codeaudit in the past and want to make sure you use the latest checks and features.
+If you have installed Python `codeaudit` in the past and want to make sure you use the latest new validations and features.
 
 ## Usage
 
@@ -91,16 +91,13 @@ codeaudit
 This will show all commands:
 
 ```text
---------------------------------------------------
-   _____          _                      _ _ _   
-  / ____|        | |                    | (_) |  
- | |     ___   __| | ___  __ _ _   _  __| |_| |_ 
- | |    / _ \ / _` |/ _ \/ _` | | | |/ _` | | __|
- | |___| (_) | (_| |  __/ (_| | |_| | (_| | | |_ 
-  \_____\___/ \__,_|\___|\__,_|\__,_|\__,_|_|\__|
---------------------------------------------------
+----------------------------------------------------
+ _                    __             _             
+|_) \/_|_|_  _ __    /   _  _| _    |_|    _| o _|_
+|   /  |_| |(_)| |   \__(_)(_|(/_   | ||_|(_| |  |_
+----------------------------------------------------
 
-Codeaudit - Modern Python source code analyzer based on distrust.
+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] 
@@ -109,19 +106,20 @@ Depending on the command, a directory or file name must be specified. The output
 
 Commands:
   overview             Reports Complexity and statistics per Python file from a directory.
-  modulescan           Reports module information per file.
-  filescan             Reports potential security issues for a single Python file.
   directoryscan        Reports potential security issues for all Python files found in a directory.
-  checks               Generate an HTML report of all implemented codeaudit security checks.
-  version              Prints the module version. Use [-v] [--v] [-version] or [--version].
+  filescan             Reports potential security issues for a single Python file.
+  modulescan           Reports module information per file.
+  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](https://nocomplexity.com/documents/codeaudit/intro.html) to check the security of Python programs and make your Python programs more secure!
+Use the Codeaudit documentation to check the security of Python programs and make your Python programs more secure!
 Check https://simplifysecurity.nocomplexity.com/ 
+
 ```
 
 ## Example
 
-By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **60 validations** implemented. 
+By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **70 validations** implemented. 
 
 The `codeaudit filescan` command shows all **potential** security issues that are detected in the source file in a HTML-report.
 

{codeaudit-0.9.3 → codeaudit-1.1.0}/README.md

@@ -7,28 +7,28 @@
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10970/badge)](https://www.bestpractices.dev/projects/10970)
 [![PyPI Downloads](https://static.pepy.tech/badge/codeaudit)](https://pepy.tech/projects/codeaudit)
 
-Python Codeaudit - A modern Python source code analyzer based on distrust.
+Python Code Audit - A modern Python source code analyzer based on distrust.
 
-Codeaudit is a tool to find security issues in Python code. This static application security testing (SAST) tool has **great** features to simplify the necessary security tasks and make it fun and easy. 
+Python Code Audit is a tool to find **security issues** in Python code. This static application security testing (SAST) tool has **great** features to simplify the necessary security tasks and make it fun and easy. 
 
-This tool is created for:
-* Anyone who want or must check security risks with Python programs.
-* Anyone who loves to create functionality using Python. So not only professional programs , but also occasional Python programmers or programmers who are used to working with other languages.
-* Anyone who wants an easy way to get insight in possible security risks Python programs.
+This tool is designed for anyone who uses or creates Python programs and wants to understand and mitigate potential security risks.
 
+This tool is created for:
+* Python Users who want to assess the security risks in the Python code they use.
+* Python Developers: Anyone, from professionals to hobbyists, who wants to deliver secure Python code.
+* Security-Conscious Users: People seeking a simple, fast way to gain insight into potential security vulnerabilities within Python packages or files.
 
-> [!WARNING]
-> Python Codeaudit is currently in *beta status*. Consider [contributing](CONTRIBUTING.md) to make Codeaudit the coolest open source Python SAST tool. Codeaudit is currently in a thorough testing phase. Use Python Codeaudit now and contribute to make it better!
+Creating secure software can be challenging. This tool, with its comprehensive [documentation](https://nocomplexity.com/documents/codeaudit/intro.html), acts as your helpful security colleague, making it easier to identify and address vulnerabilities.
 
 ## Features
 
-Python Codeaudit has the following features:
+Python Code Audit has the following features:
 
 * **Vulnerability Detection**: Identifies security vulnerabilities in Python files, essential for package security research.
 
 * **Complexity & Statistics**: Reports security-relevant complexity using a fast, lightweight [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) count via Python's AST.
 
-* **Module Usage & External Vulnerabilities**: Detects used modules and reports vulnerabilities in external ones.
+* **Module Usage & External Vulnerabilities**: Detects used modules and reports known vulnerabilities for used external modules.
 
 * **Inline Issue Reporting**: Shows potential security issues with line numbers and code snippets.
 
@@ -37,7 +37,7 @@ Python Codeaudit has the following features:
 
 
 > [!IMPORTANT]
-> Python Codeaudit uses the Python's Abstract Syntax Tree (AST) to get robust and reliable result. Using the Python AST makes contextual Vulnerability Detection possible and false positive are minimized.
+> Python Code Audit uses the Python's Abstract Syntax Tree (AST) to get robust and reliable result. Using the Python AST makes contextual Vulnerability Detection possible and false positive are minimized.
 
 
 ## Installation
@@ -48,11 +48,11 @@ pip install codeaudit
 
 or use:
 
-```bash
+```console
 pip install -U codeaudit
 ```
 
-If you have installed Codeaudit in the past and want to make sure you use the latest checks and features.
+If you have installed Python `codeaudit` in the past and want to make sure you use the latest new validations and features.
 
 ## Usage
 
@@ -65,16 +65,13 @@ codeaudit
 This will show all commands:
 
 ```text
---------------------------------------------------
-   _____          _                      _ _ _   
-  / ____|        | |                    | (_) |  
- | |     ___   __| | ___  __ _ _   _  __| |_| |_ 
- | |    / _ \ / _` |/ _ \/ _` | | | |/ _` | | __|
- | |___| (_) | (_| |  __/ (_| | |_| | (_| | | |_ 
-  \_____\___/ \__,_|\___|\__,_|\__,_|\__,_|_|\__|
---------------------------------------------------
+----------------------------------------------------
+ _                    __             _             
+|_) \/_|_|_  _ __    /   _  _| _    |_|    _| o _|_
+|   /  |_| |(_)| |   \__(_)(_|(/_   | ||_|(_| |  |_
+----------------------------------------------------
 
-Codeaudit - Modern Python source code analyzer based on distrust.
+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] 
@@ -83,19 +80,20 @@ Depending on the command, a directory or file name must be specified. The output
 
 Commands:
   overview             Reports Complexity and statistics per Python file from a directory.
-  modulescan           Reports module information per file.
-  filescan             Reports potential security issues for a single Python file.
   directoryscan        Reports potential security issues for all Python files found in a directory.
-  checks               Generate an HTML report of all implemented codeaudit security checks.
-  version              Prints the module version. Use [-v] [--v] [-version] or [--version].
+  filescan             Reports potential security issues for a single Python file.
+  modulescan           Reports module information per file.
+  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](https://nocomplexity.com/documents/codeaudit/intro.html) to check the security of Python programs and make your Python programs more secure!
+Use the Codeaudit documentation to check the security of Python programs and make your Python programs more secure!
 Check https://simplifysecurity.nocomplexity.com/ 
+
 ```
 
 ## Example
 
-By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **60 validations** implemented. 
+By running the `codeaudit filescan` command, detailed security information is determined for a Python file based on more than **70 validations** implemented. 
 
 The `codeaudit filescan` command shows all **potential** security issues that are detected in the source file in a HTML-report.
 

{codeaudit-0.9.3 → codeaudit-1.1.0}/SECURITY.md

@@ -15,7 +15,6 @@ To report a security issue, please use the GitHub Security Advisory ["Report a V
 
 I will send a response indicating the next steps in handling your report. After the initial reply to your report, I will keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance.
 
-For context on Electron's security notification process, please see the Notifications section of the Security WG's Membership and Notifications Governance document.
 
 ## Learning More About Security
 

{codeaudit-0.9.3 → codeaudit-1.1.0}/docs/CLIcommands.ipynb

@@ -13,7 +13,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 9,
    "id": "923aba22-7103-4431-8545-ee5596efa371",
    "metadata": {},
    "outputs": [],
@@ -23,7 +23,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 10,
    "id": "057c9730-7b09-49a8-82f1-bc681d880c96",
    "metadata": {},
    "outputs": [],
@@ -33,7 +33,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 11,
    "id": "67576531-b66f-42a3-b6e4-460423ca28e0",
    "metadata": {},
    "outputs": [],
@@ -44,7 +44,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 12,
    "id": "2717fe66-9e66-4fcc-ae82-0d1ba26892c4",
    "metadata": {},
    "outputs": [],
@@ -54,19 +54,19 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 13,
    "id": "3f286724-0a8f-45b2-80fe-d6d061fe440a",
    "metadata": {},
    "outputs": [],
    "source": [
     "output += '% THIS FILE IS GENERATED! - Use CLIcommands.ipynb to make it better!\\n'\n",
-    "output += '# Overview of Codeaudit commands\\n'\n",
-    "output += f'Codeaudit commands for: {version_id}'"
+    "output += '# Commands Overview\\n'\n",
+    "output += f'Python Code Audit commands for: {version_id}'"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 14,
    "id": "693c3354-530b-4a40-a561-ed722d9bb1fa",
    "metadata": {},
    "outputs": [],
@@ -77,7 +77,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 15,
    "id": "5fa9a420-bd9a-4641-99c9-de0bcf448dbc",
    "metadata": {},
    "outputs": [],
@@ -90,19 +90,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 16,
    "id": "bf6afe56-e0f7-4fa2-a3a5-968bad11bf9c",
    "metadata": {},
    "outputs": [],
    "source": [
     "commands = {  \"overview\": 'overview_report',               \n",
     "                \"modulescan\": 'report_module_information',\n",
-    "                \"filescan\" : 'file_scan_report',\n",
-    "                \"directoryscan\" : 'directory_scan_report',\n",
+    "                \"filescan\" : 'scan_report',                \n",
     "                \"checks\" : 'report_implemented_tests',\n",
     "               \"version\" : 'display_version'} \n",
     "for key, value in commands.items():    \n",
-    "    output += f'## codeaudit {key}\\n' # newlines matter when creating markdown\n",
+    "    output += f'## Code Audit {key}\\n' # newlines matter when creating markdown\n",
     "    output += '```text\\n' # raw display    \n",
     "    func_name = value\n",
     "    output += getattr(codeaudit, func_name).__doc__\n",
@@ -114,7 +113,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 17,
    "id": "0335783c-7676-4099-94c5-c98cc8f2f205",
    "metadata": {
     "editable": true,
@@ -135,7 +134,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 18,
    "id": "4667d7ec-3727-4e2d-97b5-6f597c697ec7",
    "metadata": {},
    "outputs": [],
@@ -160,7 +159,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.1"
+   "version": "3.13.5"
   }
  },
  "nbformat": 4,

{codeaudit-0.9.3 → codeaudit-1.1.0}/docs/CONTRIBUTE.md

@@ -4,6 +4,7 @@ Great that you want to contribute!
 
 :::{tip}
 All contributions are welcome!
+
 Think of corrections on the manual, code and more or better tests.
 :::
 
@@ -22,7 +23,7 @@ This simple tool is designed to be simple to use and maintain.
 
 **Pull Requests are welcome!** 
 
-When you contribute to Codeaudit, your contributions are made under the same license as the file you are working on. 
+When you contribute to Python Code Audit, your contributions are made under the same license as the file you are working on. 
 
 
 We adopt the [Collective Code Construction Contract(C4)](https://rfc.zeromq.org/spec/42/) to streamline collaboration. C4 is meant to provide a reusable optimal collaboration model for open source software projects. 

{codeaudit-0.9.3 → codeaudit-1.1.0}/docs/_toc.yml

@@ -7,11 +7,11 @@ parts:
   - file: features
   - file: userguide
     sections:
-    - file: codeauditoverview
-    - file: directoryscan
+    - file: codeauditoverview    
     - file: filescan
     - file: modulescan
     - file: codeauditchecks
+  - file: howtoscan
   - file: whysast
   - file: issues
   
@@ -26,6 +26,7 @@ parts:
     - file: checks/chmod_check
     - file: checks/binding_check
     - file: checks/directorycreation_check
+    - file: checks/dynamicimport_check
     - file: checks/exception_check
     - file: checks/tarfile_extract_check
     - file: checks/hash_check
@@ -48,18 +49,19 @@ parts:
 
 - caption: Architecture 
   chapters:     
-  # - file: astlines
+  #- file: astlines
   # - file: astlines2
+  - file: makeitbetter
   - file: complexitycheck
   - file: warnings
-  - file: codeauditcommands
-  
+  - file: codeauditcommands  
+  - file: changelog
   
   
 # - caption: API Documentation
 #   chapters:  
-#   - file: modules
-      
+#   - file: codeaudit
+   
 
 - caption: About
   chapters:  

{codeaudit-0.9.3 → codeaudit-1.1.0}/docs/astlines.md

@@ -1,9 +1,18 @@
-# AST Lines for code complexity
+# Why use AST for code complexity
 
 A simple way to count the number of lines of a file can be done with various unix commands. 
-Simple is to use the `wc` command. However counting lines is different from counting AST lines in a Python program.
+Simple is to use the `wc` command. 
+
+But counting code lines is different than counting AST lines in a Python program.
+
+:::{note} 
+AST lines give **good** indication for the complexity of a Python program.
+
+And complexity is the enemy of security! 
+
+So a low number for complexity has several advantages from a security perspective!
+:::
 
-AST lines are needed to give a more precise indication of the complexity of a Python program.
 
 
 To explain the difference between an **AST line** (as counted by the provided `count_ast_lines` function) and a **line counted by the Unix `wc` command**, let’s break it down:

codeaudit-1.1.0/docs/changelog.md

@@ -0,0 +1,4 @@
+# Change Log
+
+```{include} ../CHANGELOG.md
+```

{codeaudit-0.9.3 → codeaudit-1.1.0}/docs/checks/builtinfunctions_check.md

@@ -8,6 +8,21 @@ The Python built-in functions:
 * `compile`
 Should always be reviewed within the full context. By default use of this function is a **red** alert from a security perspective.
 
+Python Code Audit checks also on Builtin that are 'hidden':
+
+* Confusable homoglyphs like: `ℯ𝓍ℯ𝒸("print(2 + 2)")` Statements are detected.
+
+* Obfuscating usage of builtins module calls of `eval`, `exec` and `compile` like:
+```python
+import builtins
+b = builtins
+b.exec("2+2")
+```
+Or
+```python
+code_obj = d.compile('x = 5*5\nprint(x)', '<string>', 'exec')
+result = d.exec(code_obj)  #Input should not be obfuscated. Code Audit will detect this!
+```
 
 ## Why check on `eval`
 

codeaudit-1.1.0/docs/checks/dynamicimport_check.md

@@ -0,0 +1,42 @@
+# Dynamic Import Statements
+
+Using dynamic imports are a potential security issues.
+Especially if you can not validate upfront what is imported.
+
+Python Code Audit checks on:
+* `__import__`: This builtin function SHOULD never be used anymore. This is an advanced function that is not needed in everyday Python programming. 
+* `importlib.import_module` use. Using this function should be validated upfront.
+
+
+Using the dynamic imports can be a potential security issue, especially when the module name comes from an untrusted source. Often modules are fetches from internet or are imported by cleaver user input constructs in the code. But an attacker could also import the `os` module and then find a way to call functions to run commands on the system. 
+
+:::{caution} 
+Allowing dynamically module imports makes it easy to execute arbitrary code.
+:::
+
+:::{tip} 
+If the Python code or package really must use dynamic module input:
+
+Use:
+`importlib.import_module()` 
+This offers a better way to handle dynamic imports. Avoid using `__import__`.
+:::
+
+* `importlib.import_module()` is part of the standard library's importlib module, which is the modern way to interact with Python's import system programmatically. Its name clearly indicates its purpose, unlike `__import__()`, which looks like a "magic method" and is often a last resort or still found in old Python programs.
+
+* Using `importlib.import_module()` keeps dynamic import logic contained within the `importlib module`, which is maintained by the core Python developers. This is from a security point of view  preferred over directly using the low-level built-in function `__import__`.
+
+## Mitigation
+
+There is always a security risk when `importlib.import_module()` is used. 
+
+Possible mitigations:
+* **ALWAYS** use the Python Code Audit `modulescan` option for all modules within a file.
+* Check and understand what will be imported and what security risks are involved. You **MUST** never trust that dynamic imports are safe. Most are not!
+* Check if your Python program has or needs an API to download dynamic imports. 
+* If you do not trust it: Call a security expert to help you! See the [sponsor](../sponsors) page for companies that could help you!
+
+
+## References
+
+* https://docs.python.org/3/library/functions.html#import__ 

{codeaudit-0.9.3 → codeaudit-1.1.0}/docs/checks/shutil_check.md

@@ -13,9 +13,10 @@ Other implemented checks on `shutil` module methods:
 * shutil.copy2
 * shutil.copytree
 * shutil.chown
+* shutil.rmtree
 
 Note:
-* `shutil.rmtree` can be dangerous. However this call is/will be depreciated within the `shutil` module. So codeaudit will not check on this construct.
+* `shutil.rmtree` can be dangerous. However this call is/will be depreciated within the `shutil` module. For now Python Code Audit will check on usage.
 
 
 ## More information

codeaudit-1.1.0/docs/checks/zipfile_check.md

@@ -0,0 +1,56 @@
+# Zipfiles extraction
+
+When using the Python module `zipfile` there is a risk processing maliciously prepared `.zip files`. This can availability issues due to storage exhaustion. 
+
+
+Validations are done on `zipfile` methods:
+* `.extractall`
+* `.open` and more.
+
+And the methods:
+* `gzip.open`
+* `bz2.open`
+* `bz2.BZ2File` 
+* `lzma.open` 
+* `lzma.LZMAFile` 
+* `shutil.unpack_archive`
+
+## Potential danger when opening compressed files
+
+When using `gzip.open` or equivalent the potential security issue is related to resource consumption if the file is untrusted.
+
+:::{caution} 
+Never extract archives from untrusted sources without prior inspection! 
+
+It is possible that files are created outside of the path specified in the extract_dir argument, e.g. members that have absolute filenames starting with “/” or filenames with two dots “..”.
+
+:::
+
+
+This accounts also for using `bz2`, `lzma` , `shutil.unpack_archive` or `tar` compressed files. All these great Python functions that can decompress files require defense in depth to be sure that only trusted files can be opened.
+
+This can lead to:
+* **Denial of Service via Resource Exhaustion**
+If a gzip file is controlled by a malicious user, they could create a highly compressed file that expands to an enormous size when decompressed. This is known as a "zip bomb."
+
+Such `gzip` file could quickly consume all of the system's available RAM, causing the application to crash or the server to become unresponsive. This is a common attack vector when processing user-uploaded or external compressed files.
+
+* **Potential Path Traversal**
+A path traversal vulnerability could arise if the file in the `gzip` file is constructed from user input. For example, if the path came from a web request, a user could provide a path like ../../../../etc/passwd.gz to access sensitive files outside of the intended directory. This is a critical security consideration for any code that handles file paths based on external data that is decompressed with `gzip.open`.
+
+## Possible measures
+
+1. Make sure by design that these Python functions  will  **Only decompress files from trusted sources** 
+
+2. Set a limit for the  decompression size. This is not simple and always possible! The Python `lzma` library does not have a built-in parameter to do this directly. You would need to read the data in fixed-size chunks and check the total size as you go, raising an error if it exceeds a predefined limit.
+
+3. Check File Metadata: If possible, check the uncompressed size of the file from its header before starting the decompression. While not all formats contain this information, it can be a useful first check. **Note: This mitigation measurement should NEVER be used without other safeguards**
+
+4. Resource Monitoring: Monitor your application's memory,  CPU and resource usage during the decompression process and terminate it if it begins to consume an unusual amount of resources. Note that this measurement is not fail-safe!
+
+## More information
+
+* https://docs.python.org/3/library/zipfile.html#zipfile-resources-limitations
+* https://docs.python.org/3/library/gzip.html
+* https://docs.python.org/3/library/bz2.html#bz2.open
+* https://docs.python.org/3/library/shutil.html

codeaudit-1.1.0/docs/codeaudit.rst

@@ -0,0 +1,12 @@
+codeaudit package
+=================
+
+
+codeaudit.api\_interfaces module
+--------------------------------
+
+.. automodule:: codeaudit.api_interfaces
+   :members:
+   :undoc-members:
+   :show-inheritance:
+