update

Author: nocomplexity

constructs/mktemp.md

@@ -3,7 +3,7 @@
 The `tempfile.mktemp()` function in Python's standard library is **deprecated and insecure**. Its use introduces a critical **Time-of-Check to Time-of-Use (TOCTOU)** vulnerability that can be exploited by attackers to compromise your application.
 
 :::{danger} 
-**Never use `tempfile.mktemp()` in new code.** The function has been deprecated since Python 2.3 (2003) and removed from Python 3.12+ documentation as a recommended practice. Its continued use represents a significant security risk with no valid justification in modern applications.
+**Never use `tempfile.mktemp()` in new code.** The function has been deprecated and removed from Python 3.12+. But its continued use in older code bases represents a significant security risk with no valid justification in modern applications.
 :::
 
 ## Security Concerns

constructs/subprocess.md

@@ -0,0 +1,138 @@
+# Subprocess Statement
+
+
+Using Python's built-in `subprocess` module is extremely powerful for executing external commands and managing child processes. However, it also introduces significant security risks if misused.
+
+:::{caution}
+When using the `subprocess` library, your Python code can invoke arbitrary external executables on the host system.
+:::
+
+
+Python's `subprocess` module provides no mechanism to attach to the standard I/O streams of an already-running external process.
+
+## Security Concerns
+
+Legacy subprocess functions carry a **high** severity rating. You should migrate away from the older APIs to the modern `subprocess.run()` (or `subprocess.check_*` variants where appropriate).
+
+**Functions that should be avoided or reviewed carefully**:
+
+* `subprocess.call()`
+* `subprocess.Popen()` (when used directly)
+* `subprocess.check_call()`
+* `subprocess.check_output()`
+* `subprocess.getoutput()`
+* `subprocess.getstatusoutput()`
+
+## Rationale
+
+The `subprocess` module allows Python code to execute external system commands. This capability is powerful but inherently dangerous, as it creates a direct bridge between application logic (often fed by untrusted input) and the operating system shell.
+
+Common security vulnerabilities arise when:
+
+- User-controlled input is interpolated into command strings
+- The shell is invoked (`shell=True`)
+- Arguments are passed as strings instead of lists
+- Output or exit codes are trusted without proper validation
+- Errors are silently ignored or mishandled
+
+If an attacker can influence any part of the constructed command, they may achieve **command injection**, privilege escalation, data exfiltration, or remote code execution (RCE).
+
+All listed APIs are safe **by default only when used correctly** — but they are very easy to misuse.
+
+## Preventive measures
+
+These guidelines apply to **all** `subprocess` APIs:
+
+1. **Avoid `shell=True` whenever possible**  
+   This is the single biggest risk factor. Shell metacharacters (`;`, `&&`, `|`, `$()`, `` ` ``, etc.) become exploitable when the shell is involved.
+
+2. **Always pass arguments as lists, never as strings**  
+   ```python
+   # Good
+   subprocess.run(["ls", "-l", "/tmp"])
+   
+   # Bad
+   subprocess.run("ls -l /tmp", shell=True)
+   ```
+
+3. **Never concatenate or interpolate user input into command strings**  
+   This applies especially to paths, filenames, flags, or filters.
+
+4. **Validate and sanitise all inputs**  
+   Prefer allowlists over blocklists. Consider using libraries like `shlex.quote()` when string construction is unavoidable.
+
+5. **Explicitly check return codes and handle errors**  
+   Silent failures can mask partial or malicious command execution.
+
+6. **Run subprocesses with the least privileges possible**  
+   Never execute subprocesses as root (or other high-privilege users) unless absolutely necessary.
+
+7. **Prefer high-level Python APIs**  
+   Many common shell operations have safe, pure-Python equivalents in `os`, `pathlib`, `shutil`, etc.
+
+## Example
+
+### Bad example (`subprocess.call`)
+
+Highly dangerous example
+
+```python
+import subprocess
+subprocess.call("rm -rf " + user_input, shell=True)
+```
+
+**Attack scenario**:
+```python
+user_input = "/tmp/data; rm -rf /"
+```
+
+This would delete the entire filesystem (if permissions allow).
+
+### A bit better example
+
+```python
+import subprocess
+from pathlib import Path
+
+def safe_remove(path: str) -> None:
+    """Safely remove a file or directory after validation."""
+    target = Path(path).resolve()
+    
+    # Strict validation (example)
+    if not target.is_relative_to("/safe/directory"):
+        raise ValueError("Path outside allowed directory")
+    
+    subprocess.run(["rm", "-rf", str(target)], check=True)
+```
+
+
+:::{warning}
+**Important Note**
+
+Even this safer-looking code:
+
+```python
+subprocess.run(["rm", "-rf", str(target)], check=True)
+```
+
+can still introduce security weaknesses if not implemented correctly. This is why a good Python SAST tool, such as [Python Code Audit](https://github.com/nocomplexity/codeaudit), will flag the use of `subprocess.run` (and similar functions). 
+
+An expert security review is still essential, as no automated tool — including AI — can fully understand the specific context in which the code will run.
+:::
+
+## Discussion
+
+Executing shell commands or calling external applications from Python is a powerful capability, but it is **inherently dangerous**. 
+
+Wherever possible, you should use a native Python API instead of invoking shell commands. In the vast majority of cases, this is not only feasible but also significantly more secure.
+
+`Popen` is the low-level foundation and used for some advanced cases, but use `run()` for most cases if you need this kind of functionality.
+
+Using `Popen` itself is not directly a [vulnerability](vulnerability), but too often crucial checks are missing so within code `Popen` is often a weakness that should be reviewed in depth.
+
+## More information
+
+* [Official subprocess documentation](https://docs.python.org/3/library/subprocess.html)
+
+
+

constructs/systemcalls.md

@@ -0,0 +1,160 @@
+# OS System Calls
+
+Direct use of low-level operating system interfaces from the `os` module can be convenient, but it often bypasses Python’s safer, higher-level abstractions and introduces serious security risks.
+
+:::{danger}
+Be suspicious of direct `os.*` system calls in Python code. **Never trust — always verify.**
+:::
+
+The following Python `os` system calls should by default ring an alarm bell from a security point of view:
+
+* `os.system()` — executes a command in a subshell (equivalent to `subprocess` with `shell=True`).
+* The `os.exec*` family (`os.execl`, `os.execle`, `os.execlp`, `os.execlpe`, `os.execv`, `os.execve`, `os.execvp`, `os.execvpe`) — these replace the current process with a new program and **do not return**.
+* `os.fork()` — creates a child process (Unix only); can lead to fork bombs or resource exhaustion if misused.
+* `os.write()` / `os.writev()` — low-level writes to raw file descriptors.
+* And several other similar low-level functions.
+
+:::{tip}
+When shell-like functionality is required, prefer the modern `subprocess` module with proper safeguards (see the Subprocess section). Native Python APIs from `os`, `pathlib`, `shutil`, etc., are almost always safer and more portable.
+:::
+
+## Security Concerns
+
+The Python `os` functions above are powerful and easy to use, which makes them attractive — but also dangerous. 
+
+**Key risks include:**
+
+- **Command injection** (especially with `os.system()` and similar shell-invoking calls)
+- **Process replacement** (the `exec*` family terminates the current Python interpreter)
+- **Fork bombs** and resource exhaustion via `os.fork()`
+- **File descriptor mismanagement** with `os.write()` / `os.writev()`, which can lead to data corruption, arbitrary file writes, information leakage, or denial of service
+- Privilege escalation if these calls run with elevated permissions
+
+These APIs operate at a very low level and provide minimal safety checks compared to higher-level Python constructs.
+
+## Preventive measures
+
+1. **Avoid `os.system()` entirely** — use `subprocess.run()` (or `check_*` variants) with a list of arguments and `shell=False`.
+
+2. **Prefer high-level Python APIs**  
+   Use `pathlib`, `shutil`, `os.makedirs()`, `open()`, etc., instead of shelling out for file and directory operations.
+
+3. **Never pass untrusted input** to any `os` function that executes commands or writes to file descriptors.
+
+4. **Validate all inputs rigorously** (paths, filenames, descriptors, etc.). Use allowlists and resolve paths with `pathlib.Path.resolve()`.
+
+5. **Restrict privileges** — run code with the minimum necessary permissions. Avoid running as root.
+
+6. **For `os.write()` / `os.writev()`**:
+   - Only use known, validated file descriptors.
+   - Prefer Python’s file objects (`open()` / `.write()`) which provide better safety and error handling.
+
+7. **Handle `os.fork()` with extreme care** (if unavoidable) — implement proper resource limiting and error handling to prevent fork bombs.
+
+8. **Consider sandboxing** or running untrusted code in isolated environments when executing system-level operations.
+
+## Example
+
+### Bad example (`os.system`)
+
+**Dangerous — shell injection possible:**
+
+```python
+import os
+
+
+os.system("rm -rf " + user_supplied_path)
+```
+
+A simple **Attack scenario** can be:
+```python
+user_supplied_path = "/tmp/data; rm -rf /"
+```
+
+### A bit better example
+
+Example of strict allow list-style validation. Not perfect but a bit more secure.
+
+```python
+from pathlib import Path
+import subprocess
+
+def safe_remove(path: str) -> None:
+    """Safely remove a path after strict validation."""
+    target = Path(path).resolve()
+    
+    
+    allowed_root = Path("/safe/directory").resolve()
+    if not target.is_relative_to(allowed_root):
+        raise ValueError("Path outside allowed directory")
+    
+    # Use modern subprocess with list arguments
+    subprocess.run(["rm", "-rf", str(target)], check=True)
+```
+
+Please never ever do a `rm` using a Python system call.You do not needed it, there are far better alternatives!
+
+
+### More secure example (pure Python, no `rm` or subprocess)
+
+```python
+from pathlib import Path
+import shutil
+
+def safe_remove(str, allowed_root= "/safe/directory"):
+    """Safely remove a file or directory after strict validation.
+    
+    Uses pure Python standard library functions — no subprocess or shell calls.
+    """
+    try:
+        target = Path(path).resolve(strict=True)     # strict=True raises if path doesn't exist
+        root = Path(allowed_root).resolve(strict=True)
+        
+        # Strict containment check
+        if not target.is_relative_to(root):
+            raise ValueError(f"Path '{target}' is outside the allowed directory '{root}'")
+        
+        # Optional: additional explicit allowlist of permitted top-level directories
+        # if target.parent != root: ...  # further restrictions if needed
+        
+        if target.is_file() or target.is_symlink():
+            target.unlink(missing_ok=True)
+        elif target.is_dir():
+            shutil.rmtree(target, ignore_errors=False)   # do not ignore errors #nosec - Can be ignored by SAST scan
+        else:
+            raise ValueError(f"Path '{target}' is neither a file nor a directory")
+            
+    except Exception as e:
+        raise RuntimeError(f"Failed to safely remove '{path}': {e}") from e
+```
+
+This example is better and more secure:
+
+- **No subprocess or shell** — completely avoids `rm`, `os.system`, etc.
+- Uses `pathlib.Path` + `shutil.rmtree` — the idiomatic, safe Python way.
+- `resolve(strict=True)` ensures the path actually exists and resolves symlinks safely.
+- Clear exception handling with context.
+- `missing_ok=True` on files prevents unnecessary errors.
+- `ignore_errors=False` on `rmtree` ensures failures are not silently ignored.
+- Easy to extend with more validation (e.g. file type checks, size limits, etc.).
+
+:::{note} Note
+
+**Never use shell commands or low-level system calls when a safe native Python API exists.**
+:::
+
+
+## Discussion
+
+Low-level `os` calls are sometimes necessary for performance or very specific system interactions, but they should be treated as advanced and potentially **hazardous** features. 
+
+In most applications, you can achieve the same goals more securely and portably using Python’s standard library abstractions. When process management or command execution is truly needed, the `subprocess` module (used correctly) is the recommended approach.
+
+Always assume that any direct system call may be misused and design your code with defence-in-depth principles.
+
+## More information
+
+* [Official `os` module documentation](https://docs.python.org/3/library/os.html)
+* [CWE-78: OS Command Injection](https://cwe.mitre.org/data/definitions/78.html)
+* [Fork bomb / Rabbit virus attacks](https://www.imperva.com/learn/ddos/fork-bomb/)
+

fundamentals/whatissast.md

@@ -125,7 +125,7 @@ At a function level, Python Code Audit makes use of a common technique to scan t
 Simple good cyber security is possible by [Shift left](https://nocomplexity.com/documents/simplifysecurity/shiftleft.html). By detecting issues early in the SLDC process the cost to solve potential security issues is low. 
 
 
-
+(vulnerability)=
 ## Difference Between Weakness and Vulnerability
 
 Every Python SAST tool — including [Python Code Audit](../securitytools/codeaudit.md) — scans your codebase for potential security issues. These tools flag **weaknesses** that *could* lead to exploitable security vulnerabilities.

toc.yml

@@ -46,6 +46,8 @@ project:
         - file: constructs/ftp.md
         - file: constructs/marshal.md
         - file: constructs/mktemp.md
+        - file: constructs/subprocess.md
+        - file: constructs/systemcalls.md
 
 
     - file: guidelines/guidelines_intro.md