codeaudit 1.1.0__tar.gz → 1.2.0__tar.gz

{codeaudit-1.1.0 → codeaudit-1.2.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Change Log
 
+# Version 1.2: Changes and Updates
+
+* fix: Improved error handling — when performing a file scan on a single Python file that cannot be parsed, the CLI now correctly displays an error message.
+
+* fix: Updated API logic to properly handle parsing errors for single Python files.
+
+* fix: Corrected validation descriptions for `os.write` and `os.writev`. Writing to unvalidated or unintended file descriptors can lead to data corruption, privilege escalation, or denial of service.
+
+* fix: Internal API functions now use a leading underscore (`_`) to clearly distinguish them from public APIs.
+
+* **new**: Added a function for weakness visualization. Refer to the examples for usage details.
+
+* **new**: Added API documentation and examples for usage details.
+
+
 ## 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeaudit
-Version: 1.1.0
+Version: 1.2.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
@@ -35,7 +35,8 @@ Description-Content-Type: text/markdown
 
 Python Code Audit - A modern Python source code analyzer based on distrust.
 
-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. 
+Python Code Audit is a tool to find **security weaknesses** 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 designed for anyone who uses or creates Python programs and wants to understand and mitigate potential security risks.
 
@@ -62,7 +63,7 @@ Python Code Audit has the following features:
 
 
 
-> [!IMPORTANT]
+> [!NOTE]
 > 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.
 
 
@@ -106,9 +107,8 @@ 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.
-  directoryscan        Reports potential security issues for all Python files found in a directory.
-  filescan             Reports potential security issues for a single Python file.
-  modulescan           Reports module information per file.
+  filescan             Scans Python files or directories(packages) for vulnerabilities and reports potential issues.
+  modulescan           Reports module vulnerability information.
   checks               Creates an HTML report of all implemented security checks.
   version              Prints the module version. Or use codeaudit [-v] [--v] [-version] or [--version].
 

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

@@ -9,7 +9,8 @@
 
 Python Code Audit - A modern Python source code analyzer based on distrust.
 
-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. 
+Python Code Audit is a tool to find **security weaknesses** 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 designed for anyone who uses or creates Python programs and wants to understand and mitigate potential security risks.
 
@@ -36,7 +37,7 @@ Python Code Audit has the following features:
 
 
 
-> [!IMPORTANT]
+> [!NOTE]
 > 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.
 
 
@@ -80,9 +81,8 @@ 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.
-  directoryscan        Reports potential security issues for all Python files found in a directory.
-  filescan             Reports potential security issues for a single Python file.
-  modulescan           Reports module information per file.
+  filescan             Scans Python files or directories(packages) for vulnerabilities and reports potential issues.
+  modulescan           Reports module vulnerability information.
   checks               Creates an HTML report of all implemented security checks.
   version              Prints the module version. Or use codeaudit [-v] [--v] [-version] or [--version].
 

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

@@ -141,6 +141,14 @@
    "source": [
     "create_documentation_file(output)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fd67a8f6-ed99-4f69-ab55-aad6103c7b5c",
+   "metadata": {},
+   "source": [
+    "## Create overview of validation commands for in documentation"
+   ]
   }
  ],
  "metadata": {

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

@@ -37,6 +37,16 @@ This project values respect and inclusiveness, and enforces a [Code of Conduct](
 This is an open community driven project. Contributors will be mentioned in the documentation.
 :::
 
+## Help with development
+
+:::{admonition} Start with Code Development
+:class: tip
+Making code contributions to **Python Code Audit** should be fun and simple!
+
+See the [section Development](makeitbetter) for to get a head start when making code contributions!
+
+:::
+
 (CoC-label)=
 ## Code of Conduct
 

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

@@ -12,12 +12,14 @@ parts:
     - file: modulescan
     - file: codeauditchecks
   - file: howtoscan
+  - file: whatissast
   - file: whysast
   - file: issues
   
 
 - caption: Security Checks
   chapters:
+  - file: implementedvalidations
   - file: checksinformation
     sections:
     - file: checks/assert_check
@@ -58,9 +60,15 @@ parts:
   - file: changelog
   
   
-# - caption: API Documentation
-#   chapters:  
-#   - file: codeaudit
+- caption: API Documentation
+  chapters:  
+  - file: apidocs/api_intro
+    sections:    
+    - file: examples/ca_api_example_overview
+    - file: examples/ca_api_example_json
+    - file: examples/ca_api_example_basic
+  - file: apidocs/modules
+  
    
 
 - caption: About
@@ -70,3 +78,4 @@ parts:
   - file: sponsors
   - file: license
   - file: about
+

codeaudit-1.2.0/docs/apidocs/api_intro.md

@@ -0,0 +1,19 @@
+# Python Code Audit APIs
+
+The **Python Code Audit** APIs make it easy to build your own tools and integrations, such as:
+
+
+* **Reporting dashboard**: Easily create custom dashboards using the APIs. Audit scan results can be exported to a human-readable JSON file for analysis and visualization.
+
+* **Statistical Analysis**:
+Use the APIs to identify and study common Python security weaknesses across multiple packages within your organization.
+
+
+* **CI/CD Integration**:
+Integrate the APIs into your continuous integration and deployment pipelines — even when using remote source control systems like `GitHub.com`, `GitLab.com`, `https://codeberg.org/` or https://notabug.org/ and many others!
+
+We’ve provided a few simple examples to demonstrate how to use the APIs effectively.
+
+
+```{tableofcontents}
+```

codeaudit-1.2.0/docs/apidocs/codeaudit.rst

@@ -0,0 +1,12 @@
+Code Audit Public APIs 
+=======================
+
+
+Public Interfaces module
+------------------------
+
+.. automodule:: codeaudit.api_interfaces
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

{codeaudit-1.1.0/docs → codeaudit-1.2.0/docs/apidocs}/modules.rst

@@ -1,5 +1,5 @@
-codeaudit
-=========
+API Reference 
+==============
 
 .. toctree::
    :maxdepth: 4

{codeaudit-1.1.0 → codeaudit-1.2.0}/docs/checks/assert_check.md

@@ -3,7 +3,7 @@
 The Python `assert` statement itself is not insecure, but its *misuse* can lead to security vulnerabilities. 
 
 :::{danger} 
-Using `assert` can be problematic from a security perspective!
+Using `assert` for checks can introduce **serious security** risks!
 :::
 
 
@@ -21,18 +21,50 @@ This means any crucial checks you rely on for security or data integrity will si
 
 * **Not for graceful error handling:** Assertions are designed to signal "this should never happen, it's a bug." They raise an `AssertionError` which typically halts the program. In a production environment, you usually want to handle anticipated errors gracefully, log them, and potentially recover or inform the user, rather than crashing the application.
 
-2. Some side effects within `assert` statements can be dangerous.
+2.  Dangers of Side effects in assert Statements:
 
-* If an `assert` statement contains code with side effects (e.g., modifying a variable, calling a function that performs an action), those side effects will also be skipped when assertions are disabled. This can lead to unexpected behavior and security gaps.
+* If an assert statement contains code with side effects (e.g., modifying a variable or calling a function that performs an action), those side effects will also be skipped when assertions are disabled. For example, when running Python with the -O optimization flag. This can lead to unexpected behaviour and even security vulnerabilities.
 
-3. Use assert for testing code and during development only
+* If you rely on `assert` to prevent a `ZeroDivisionError` or validate user input, those checks will silently disappear in optimized environments. As a result, code may behave differently than intended, creating potential security gaps.
+
+* Relying on assert for input validation is especially dangerous. If assertions are used to block malicious input (e.g., to prevent SQL injection or enforce type checks), an attacker could exploit the fact that these validations are stripped out in production.
+
+* If an `assert` statement contains code with side effects (e.g., modifying a variable, calling a function that performs an action), those side effects will also be skipped when assertions are disabled. This can lead to unexpected behaviour and security gaps.
+
+* Instead of catching an AssertionError, a program can run differently. This can have severe security consequences. E.g. if asserts are used to validate user input to prevent sql injections or user input.
+
+
+## Preventive measures
+
+
+1. Use assert for testing code and during development only!
 
 * `assert` is good to use for `pytest` or other development constructs. 
 
 * `Assert` helps to find mistakes during development. But it is not a security fence to protect against external threats or a robust mechanism for handling runtime issues in a live system. For production code, especially when dealing with external inputs or critical business logic, rely on explicit `if/else` checks and robust exception handling.
 
  * `Assert` statements should in general only be used for testing and debugging purposes. 
- `assert` statements **SHOULD** be removed when not running in debug mode (i.e. when invoking the Python command with the -O or -OO options).
+ 
+ `assert` statements **SHOULD** be removed when not running in debug mode. This means when invoking the Python command with the -O or -OO options.
+
+2. Use explicit condition checks and raise proper exceptions (e.g., `ValueError`, `TypeError`) for input validation and critical logic. 
+
+3. **Never ever** use `assert` in production Python code for checks. 
+
+4. The **only** safe alternative: Explicit Checks!
+
+
+For production code, especially when handling external inputs or executing critical logic, always rely on explicit condition checks and robust exception handling.
+
+:::{admonition} Instead of an assert, use standard control flow and exception raising
+:class: hint
+
+* Use if/else checks: Explicitly validate inputs and conditions.
+
+* Raise proper exceptions: Use dedicated exceptions like `ValueError`, `TypeError`, or a custom exception to signal an issue. This provides a robust mechanism that can be caught and handled gracefully by upstream code, logging a clear error message instead of silently failing or creating a security hole.
+
+:::
+
 
 
 ## Example

codeaudit-1.2.0/docs/checks/builtinfunctions_check.md

@@ -0,0 +1,138 @@
+# Built-in Functions
+
+Some Python built-in functions can cause severe risks. 
+
+The Python built-in functions:
+* `eval`
+* `exec` and
+* `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`
+
+:::{admonition} Security risk
+:class: danger
+`eval()` can execute arbitrary Python code. 
+
+If the input is user-controlled or from an untrusted source, this can be exploited.
+:::
+
+So calling `eval` with user-supplied input may lead to security vulnerabilities.
+
+The `eval` function can also be used to execute arbitrary code objects (such as those created by `compile()`). 
+
+Normal Python programs should not need to use this built-in function.
+
+
+The primary security concern with Python’s built-in `eval()` is its potential to enable **Remote Code Execution (RCE)**. Passing untrusted input to `eval()` is effectively the same as letting an attacker run arbitrary Python code on your system.
+
+Key Security Risks when using `eval`:
+
+1. **Arbitrary Code Execution (RCE)**
+
+   * `eval()` runs any Python code in the string it receives. If an attacker controls that string, they can execute malicious commands—stealing data, reading files, or invoking dangerous modules like `os` or `subprocess`.
+
+2. **Broken Sandboxing**
+
+   * Attempts to make `eval()` “safe” by restricting variables or the execution environment are unreliable. Attackers often find creative ways to escape these sandboxes and access sensitive data, functions, or the file system.
+
+3. **Denial of Service (DoS)**
+
+   * Even without stealing data, attackers can craft inputs that trigger infinite loops, deep recursion, or memory exhaustion. This can crash the interpreter or take down an entire service.
+
+
+
+:::{warning} 
+This function is capable of executing any Python code given to it. Passing unvalidated external input (such as user input, or file contents , or API retrieved content) is a major security flaw that enables arbitrary code execution. 
+
+**Never ever not use this function on data from untrusted sources.**
+:::
+
+## Why Check on `exec`
+
+:::{danger} 
+The use of the exec() function in Python should never be permitted from a security perspective. 
+
+It can executes arbitrary code. Or be called with untrusted input. This is a direct path to a severe security compromise.
+:::
+
+This function executes arbitrary code. Calling it with user-supplied input may lead to security vulnerabilities.
+
+
+Using `exec` in Python should never be tolerated from a security perspective. Key risks are:
+
+1. **Arbitrary Code Execution:** Executes any string as Python code; untrusted input can lead to full system compromise.
+2. **Sandboxing Fails:** Attempts to restrict execution are often bypassed.
+3. **Denial of Service:** Malicious code can cause infinite loops or memory exhaustion.
+4. **Injection Risk:** Dynamic code with user input creates exploitable injection points.
+5. **Hidden Side Effects:** Alters variables or global state unpredictably, introducing security and reliability issues.
+
+
+
+
+
+## Why check on `compile`
+
+As a general rule:
+* Never trust Python code that uses `compile`. Verify and understand all risks before running such a program.
+
+Security reasons to avoid Python’s built-in `compile()`:
+
+1. **Arbitrary Code Execution**
+
+   * `compile()` takes raw strings and turns them into executable Python code objects. If user input is passed to it (directly or indirectly), an attacker can execute arbitrary Python code on your system.
+
+2. **Bypassing Sandboxing or Input Validation**
+
+   * Using `compile()` can allow malicious input to bypass normal validation layers. Even if you sanitise strings for SQL or HTML, a crafted payload compiled into Python bytecode can escape restrictions.
+
+3. **Denial of Service (DoS) via Resource Exhaustion**
+
+   * Large or deeply nested input passed to `compile()` can consume huge amounts of CPU, memory, or recursion depth, potentially crashing the interpreter (e.g., from complex expressions or nested structures).
+
+4. **Exposure of Sensitive Data**
+
+   * Once arbitrary code is compiled and run, it can access system resources, environment variables, secrets in memory, or files on disk—leading to credential leaks or other security breaches.
+
+
+
+:::{warning} 
+Compiling very large or deeply nested strings into an AST object can crash the Python interpreter. This happens because Python’s AST compiler has stack depth limitations, which may be exceeded by sufficiently complex input.
+:::
+
+:::{warning} 
+Also the construct `ast.literal_eval` is not safe!
+Using this construct can still crash the Python interpreter due to stack depth limitations in Python’s AST compiler.
+
+[Reference](https://docs.python.org/3/library/ast.html#ast.literal_eval)
+:::
+
+## Preventive measures
+
+* Avoid using `eval`,`exec` and `compile`: Find a secure way by design, so rethink your design again from a security perspective. There is always a better and safer solution.
+
+
+
+## More information
+
+* https://docs.python.org/3/library/functions.html#eval 
+
+* https://docs.python.org/3/library/functions.html#exec
+
+* https://docs.python.org/3/library/functions.html#compile

{codeaudit-1.1.0 → codeaudit-1.2.0}/docs/checks/input_check.md

@@ -13,7 +13,9 @@ Validate/sanitize all input thoroughly before using it in any part of your appli
 :::
 
 
-## Common security concerns with the use of `input()` in Python 
+## Security concerns 
+
+Common security concerns with the use of `input()` in Python are:
 
   * **Injection Attacks:** If you take user input and directly embed it into:
       * **SQL queries:** SQL Injection (e.g., a user enters `' OR 1=1; --` to bypass login).
@@ -28,7 +30,9 @@ Validate/sanitize all input thoroughly before using it in any part of your appli
   
   * **Revealing Sensitive Information:** If your error handling is too verbose and displays raw error messages that include sensitive system paths or internal details based on user input, attackers can use this information for further exploitation.
 
-## Some simple rules for handling User Input
+## Preventive measures
+
+Some simple rules for handling User Input:
 
 1.  **Always Validate Input:**
 
@@ -57,3 +61,8 @@ Never ever use `eval()` or `exec()` with user-provided strings.
 
 6.  **Secure Error Handling:** Don't display raw error messages to users. Log them for internal review and provide generic, user-friendly error messages instead.
 
+## More information
+
+* [CWE-77: Improper Neutralization of Special Elements used in a Command ('Command Injection')](https://cwe.mitre.org/data/definitions/77.html)
+* [CWE-79: Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')](https://cwe.mitre.org/data/definitions/79.html) 
+* [CWE-20: Improper Input Validation](https://cwe.mitre.org/data/definitions/20.html)

codeaudit-1.2.0/docs/checks/systemcalls_check.md

@@ -0,0 +1,76 @@
+# OS System calls 
+
+:::{danger} 
+Be suspicious when direct system calls `os.*` are used in a Python program.
+:::
+
+
+*Never trust always verify!* 
+
+So direct systems calls from a Python program **SHOULD** always be verified. System calls can be major security risk. But are nice and easy to use. So often these calls are used. But not always in the correct way!
+
+`codeaudit` checks on:
+*  `os.system` : A nice command to execute OS things are malware in a subshell.
+* os.execl(path, arg0, arg1, ...)
+* os.execle(path, arg0, arg1, ..., env)
+* os.execlp(file, arg0, arg1, ...)
+* os.execlpe(file, arg0, arg1, ..., env)
+* os.execv(path, args)
+* os.execve(path, args, env)
+* os.execvp(file, args)
+* os.execvpe(file, args, env)
+* `os.fork`
+* `os.write`
+* `os.writev`
+* and more!
+
+These functions all can execute a new program, replacing the current process; they do not return. On Unix, the new executable is loaded into the current process, and will have the same process id as the caller.
+
+:::{tip} 
+When shell commands are used, make sure you understand possibly security consequences. Besides malware most common is that the availability is at risks when file systems are filled with files or logfiles.
+:::
+
+
+## Why `os.write` can be Vulnerable: File Descriptor Mismanagement
+
+The vulnerability of the `os.write(fd, data)` function in Python stems not from the function itself, but from its **low-level interaction with file descriptors (FDs)**, which bypasses standard, safer I/O abstractions. 
+The function writes raw bytes directly to a numerical file descriptor `fd`.
+
+The primary risk is the use of an **unvalidated or attacker-controlled file descriptor (FD)**. This can lead to severe security and stability issues:
+
+
+1. Data Corruption and Integrity Compromise 💾
+
+If an attacker can control the `fd` argument, they could redirect the output to an unintended file:
+
+* **Sensitive File Overwriting:** Writing to critical system files (e.g., configuration files like `/etc/passwd` or `/etc/shadow`, log files, or application binaries) can **corrupt system integrity** or **allow privilege escalation** if the data contains malicious commands or changes authentication data.
+* **Arbitrary File Write:** The attacker can potentially **overwrite any file** the process has write permissions for.
+
+
+2. Information Leakage and Data Injection ✉️
+
+File descriptors aren't just for disk files; they can also point to **sockets, pipes, or other inter-process communication (IPC) channels**.
+
+* **Inter-Process Data Injection:** Writing to a pipe or socket `fd` used by another process can **inject arbitrary, unvalidated data** into that process's data stream. For example, injecting malicious commands into a shell session or corrupted data into a communication stream.
+
+
+3. Denial of Service (DoS) 🛑
+
+Mismanagement of FDs can directly impact system stability or resource availability.
+
+* **Resource Exhaustion:** If `fd` points to a device or a pipe that is not being read, excessive writes can fill up buffers, causing the application or system to hang or crash due to resource exhaustion.
+* **Service Interruption:** Writing gibberish to an active and expected stream can immediately crash or hang the receiving application, causing a **denial of service**.
+
+
+### Preventive measures
+
+
+Always ensure that file descriptors used with $\mathtt{os.write}$ are **validated** and **tightly controlled**. It is generally safer to use Python's built-in file handling (e.g., the $\mathtt{open()}$ function and $\mathtt{file.write()}$ method), which operates at a higher level of abstraction and typically includes more robust error and permission handling.
+
+
+## More information
+
+* https://docs.python.org/3/library/os.html#os.popen
+* https://cwe.mitre.org/data/definitions/78.html
+* [Python Fork Bomb](https://medium.com/@BuildandDebug/python-fork-bomb-a-one-liner-that-can-crash-your-system-652540c7d89f)
+* [Fork bomb attack (Rabbit virus)](https://www.imperva.com/learn/ddos/fork-bomb/)

codeaudit-1.2.0/docs/checks/tarfile_extract_check.md

@@ -0,0 +1,76 @@
+# TarFile Statement
+
+The Python `tarfile` module makes it possible to read and write tar archives.
+
+Code Audit checks on the use of:
+* `TarFile.extract` and
+* `TarFile.extractall`
+Using these methods in Python code can give serious security concerns.
+
+
+:::{admonition} The default rule is:
+:class: danger
+Assume all input is malicious.
+:::
+
+Using these commands in Python code can expose systems to several risks:
+
+* Privilege escalation: An attacker can change file permissions on sensitive files (for example, `/etc/shadow` or SSH keys) if the extraction process runs with root or elevated privileges.
+
+* Sandbox escape: Many systems rely on extraction directories or temporary paths for isolation; malicious archives can break that isolation and allow code to operate outside the sandbox.
+
+* Tampering and log evasion: By modifying file timestamps or other metadata, an attacker can obscure activity, confuse forensic timelines, or mislead incident response.
+
+* Easy exploitation: Crafting a malicious tarball is straightforward and requires no specialized tools, making exploitation trivial for an attacker.
+
+
+:::{danger} 
+Using `TarFile.extractall` or `TarFile.extract` is dangerous.
+Always. So good mitigation measurement **must** be present in the code!
+:::
+
+But besides using these `tarfile` commands in your Python code, there have been some vulnerabilities with the `tarfile` module implementation in CPython in the past. 
+
+So from a security point of view checking if your code is extracting files using the `tarfile` command is vital. 
+
+:::{note} 
+Use of the `tarfile` extraction methods in Python code should **always** be reviewed in depth! 
+
+This means:
+* Check if the code uses defence in-depth measures for extracting files. 
+
+* Check if the files that will be extracted by the Python code can be assumed secure, so not tampered with. If not: validate if enough additional mitigation measurements are in place when using this code. 
+
+Mitigation measurements are always context dependent, and can be e.g. running the Python program in an isolated environment.
+:::
+
+## Preventive measures
+
+Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of path, e.g. members that have absolute filenames starting with `"/"` or filenames with two dots `".."`.
+
+Make sure a proper `filter` is set:
+```
+TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)
+```
+The filter argument specifies how members are modified or rejected before extraction. So set minimal `filter='data'` to prevent the most dangerous security issues, and read the Extraction filters section documentation for details.
+
+
+* Do not pass filter="tar" or filter="data" for untrusted archives.
+If you must unpack, force filter="none" and run in a dedicated, non-privileged container/VM.
+
+:::{note} 
+This validation test requires **always** human inspection if the construct is detected.
+No automatic test can give you enough confidence! So **no AI agent or other GenAI thing** will help you. 
+
+Using this construct is fine, but make sure you known how to prevent disasters!
+:::
+
+## More info
+
+* [CVE-2025-4330](https://www.cve.org/CVERecord?id=CVE-2025-4330)
+* [CVE-2024-12718](https://nvd.nist.gov/vuln/detail/CVE-2024-12718)
+* [CWE-22: Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')](https://cwe.mitre.org/data/definitions/22.html)
+* https://docs.python.org/3/library/tarfile.html#tarfile-extraction-filter 
+* [What Is The Tarfile Vulnerability in Python?](https://www.securitycompass.com/kontra/what-is-the-tarfile-vulnerability-in-python/) 
+* [Summary of Python tarfile Infinite Loop Vulnerability (CVE-2025-8194)](https://zeropath.com/blog/cve-2025-8194-python-tarfile-infinite-loop)
+* [Tarfile: Exploiting the World With a 15-Year-Old Vulnerability](https://www.trellix.com/blogs/research/tarfile-exploiting-the-world/)

codeaudit-1.2.0/docs/checksinformation.md

@@ -0,0 +1,44 @@
+# Information on checks
+
+**Python Code Audit** has many implemented security checks based on possible security threats when using Python Standard Library (PSL) calls.
+
+Checks are done to determine:
+* **If** and
+* **Where**
+
+Python source code uses functions or classes that are a security weakness.
+
+A security weakness is a flaw, design choice, or implementation issue that could potentially lead to a security problem — but isn’t necessarily exploitable by itself.
+
+:::{admonition} **Review**, **remediate**, and **validate** all identified security weaknesses in the code!
+:class: tip
+Ensure that all reported **security findings** are fully addressed. The code must be thoroughly reviewed and corrected to eliminate weaknesses and prevent potential exploitation as **vulnerabilities**.
+
+:::
+
+
+
+
+The majority of validations is done using advanced AST parsing of Python files. Parsed code is **not** compiled or executed. This to prevent security issues when using this tool!
+
+Due to using the AST for validations implemented constructs code that use Python Standard Library modules that can be in potential cause a security issue. Also when aliases are used constructs will be detected. Aliases in code are often not directly detected with a 'human' code review. Sometimes even on purpose!
+
+To check if an imported function is used several cases of occurrence  will be detected. For e.g. `os.access`  call:
+* import os
+* import os as alias	
+* from os import access	
+* from os import access as x
+
+So the following `clown` construct is detected, since **Python Code Audit** checks on use of the `system` method of the `os` module.
+```python
+from os import system as clown
+clown('ls -la')
+```
+
+## Validations overview
+
+
+In the following subsections detailed information on implemented security validations:
+```{tableofcontents}
+```
+

codeaudit-1.2.0/docs/codeauditchecks.md

@@ -0,0 +1,22 @@
+# Command `codeaudit checks`
+
+The `codeaudit checks` command creates a report with all security validation implemented for that are used for the `filescan` scan command. 
+
+
+To use the `codeaudit checks` feature type in the console:
+
+```
+codeaudit checks
+```
+
+This will generate a HTML report, including the version of Python Code Audit that is installed.
+
+Example output as HTML [click to see](examples/checks.html), or see below as embedded HTML:
+
+:::{attention} 
+Always use the latest version to have the latest security validations!
+
+Update your local installation with:
+```bash
+pip install -U codeaudit
+```