updates

Author: nocomplexity

constructs/exceptions.md

@@ -0,0 +1,169 @@
+# Exception Statements
+
+## Rationale or Security Concerns
+
+The use of Python exception statements becomes a critical security weakness when `pass` or `continue` is used for exception handling. This pattern is inherently dangerous as it creates silent failure conditions that can mask security vulnerabilities and enable attacks.
+
+
+The Python pattern:
+```python
+try:
+    do_some_stuff()
+except Exception:
+    pass
+```
+
+presents severe security risks due to:
+
+- **Overly broad exception handling** – catching `Exception` masks virtually all errors, including security-critical ones
+- **Silent failure** – using `pass` suppresses all evidence that something went wrong
+- **Arbitrary Code Execution Risk** – If `do_some_stuff()` involves deserialization (e.g., `pickle.loads()`), catching and ignoring exceptions could hide successful exploitation of deserialization vulnerabilities that lead to arbitrary code execution
+- **Attack Vector Concealment** – Attackers can deliberately trigger exceptions as part of reconnaissance or exploitation, and the silenced errors provide no defensive alerts
+
+
+This pattern often appears due to:
+- **Use of AI coding tools** :Many AI vibe coding tools will produce `pass` in exception handling functions by default. 
+- **Developer convenience**: Quick "fix" to prevent crashes without addressing root causes
+- **Misguided stability attempts** : Belief that catching all errors ensures application stability
+- **Lack of security awareness**: Developers unaware of the security implications
+
+### Inherent Security Risks 
+
+1. **Masking of Critical Errors and Vulnerabilities:**
+   - **Hiding Bugs:** Any exception, from a simple `TypeError` to a critical `MemoryError` or a security-related issue like an `InjectionError` (if `do_some_stuff()` interacts with databases or external systems), will be silently caught and ignored
+   - **Undetected Attacks:** If an attacker triggers an exception as part of an exploit (e.g., a buffer overflow causing specific exceptions, invalid input leading to unhandled conditions), the `except Exception: pass` block swallows it. The attack might succeed without any indication
+   - **Resource Leaks:** If `do_some_stuff()` involves opening files, network connections, or acquiring locks, exceptions occurring before proper cleanup can lead to resource exhaustion, denial-of-service (DoS), or data corruption
+
+2. **Denial of Service (DoS) Vulnerabilities:**
+   - **Infinite Loops/Stuck Processes:** An error within `do_some_stuff()` leading to infinite loops or stuck processes won't be reported, potentially making the application unresponsive and vulnerable to DoS attacks
+   - **Resource Exhaustion:** Silenced exceptions prevent proper cleanup, allowing resource leaks to accumulate over time
+
+3. **Compromised Data Integrity and Consistency:**
+   - If `do_some_stuff()` performs data-modifying operations (database writes, file manipulations), exceptions can leave data in inconsistent or corrupted states. Silently ignoring these means the program continues, potentially propagating bad data
+
+4. **Lack of Forensic Information:**
+   - No logging, no traceback, no indication of what went wrong severely hinders post-mortem analysis and incident investigation
+
+5. **Compliance Failures:**
+   - For security audits and compliance requirements (GDPR, HIPAA, PCI DSS), robust error handling is a necessity. Silenced exceptions make it impossible to demonstrate appropriate error management
+
+
+## Preventive Measures / Mitigations
+
+### Safer Alternatives
+
+**1. Be Specific – Catch Only Expected Exceptions:**
+Always catch specific exceptions you anticipate and know how to handle:
+```python
+try:
+    do_some_stuff()
+except ValueError:
+    handle_value_error()
+except FileNotFoundError:
+    handle_missing_file()
+```
+
+**2. Log Exceptions Properly:**
+Even if choosing not to crash, always log the exception with full traceback:
+```python
+import logging
+
+logging.basicConfig(level=logging.ERROR)
+
+try:
+    do_some_stuff()
+except Exception as e:
+    logging.error("Unexpected error in do_some_stuff()", exc_info=True)
+    # Optionally re-raise if program cannot continue meaningfully
+    # raise
+```
+
+**3. Use `finally` or Context Managers for Cleanup:**
+Ensure resource cleanup regardless of exceptions:
+```python
+try:
+    f = open("my_file.txt", "r")
+    # ... do stuff with f ...
+except FileNotFoundError:
+    print("File not found!")
+finally:
+    if 'f' in locals() and not f.closed:
+        f.close()        
+```
+
+Even better using `with` :
+```python
+try:
+    with open("my_file.txt", "r") as f:
+        # ... do stuff with f ...
+        pass
+except FileNotFoundError:
+    print("File not found!")
+```
+
+
+**4. Implement Graceful Degradation:**
+Rather than failing silently, provide meaningful fallback behavior:
+```python
+try:
+    result = fetch_from_external_service()
+except ExternalServiceError as e:
+    logging.critical("External service unavailable", exc_info=True)
+    result = get_cached_data()  # Fallback
+```
+
+**5. Use Cryptographic Signing for Validation:**
+For deserialization operations, consider using `hmac` or `safetensors`:
+```python
+import hmac
+import hashlib
+import pickle
+
+def secure_load(data, key):
+    """Load pickled data only if signature is valid."""
+    signature = data[:32]  # Prepend signature
+    payload = data[32:]
+    
+    expected = hmac.new(key, payload, hashlib.sha256).digest()
+    if not hmac.compare_digest(signature, expected):
+        raise ValueError("Invalid signature - possible tampering")
+    
+    return pickle.loads(payload)
+```
+
+## Discussion
+
+### When Is Silent Exception Handling Acceptable?
+
+Rarely. Some valid but limited scenarios include:
+- **Cleanup operations where failure is non-critical** (but still log)
+- **Context managers where the only purpose is resource management**
+- **Hook functions where exceptions from one handler shouldn't affect others** (but log each)
+
+Always document why an exception is being ignored.
+
+### The `continue` Variation
+
+Using `continue` within a loop's exception handler similarly bypasses error reporting:
+```python
+for item in data:
+    try:
+        process(item)
+    except Exception:
+        continue  # Just as dangerous as pass
+```
+
+
+
+
+
+
+## More Information
+
+- [CWE-248: Uncaught Exception](https://cwe.mitre.org/data/definitions/248.html)
+- [CWE-703: Improper Check or Handling of Exceptional Conditions](https://cwe.mitre.org/data/definitions/703.html)
+- [CWE-456: Missing Initialization of a Variable](https://cwe.mitre.org/data/definitions/456.html)
+- [CWE-391: Unchecked Error Condition](https://cwe.mitre.org/data/definitions/391.html)
+- [Python Exception Handling Best Practices](https://docs.python.org/3/tutorial/errors.html)
+- [OWASP Error Handling Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html)
+

constructs/ftp.md

@@ -0,0 +1,138 @@
+# FTP Statement
+
+The use of `ftplib.FTP` from Python's standard library is **insecure and should be avoided** in modern application development. This class implements the legacy File Transfer Protocol (FTP), which lacks native encryption for both authentication and data transmission.
+
+:::{danger} 
+Never ever allow or use `ftplib.FTP`.
+
+Even within isolated or private networks, the risk of credential theft and data interception is unacceptably high. Always implement protocols that secure data transfers by default.
+:::
+
+## Security Concerns
+
+Using `ftplib.FTP` introduces several critical vulnerabilities that compromise the confidentiality and integrity of your data:
+
+### Cleartext Credentials
+Usernames and passwords are transmitted in plain text over the network, making them trivial to intercept via packet sniffing tools such as Wireshark or tcpdump.
+
+### Unencrypted Data Transfer
+File contents, directory structures, and command responses are sent without encryption. This exposes sensitive information to eavesdropping and allows attackers to read or modify data in transit.
+
+### Man-in-the-Middle (MITM) Attacks
+Because FTP lacks cryptographic integrity checks, an attacker positioned between the client and server can capture, alter, or inject malicious content into the communication stream undetected.
+
+### Deceptive Aliasing
+Renaming the class (e.g., `from ftplib import FTP as SecureFTP`) provides no technical security whatsoever and is **dangerously misleading**. This practice can create a false sense of security among developers and should be strictly prohibited in code reviews.
+
+### Firewall and NAT Complications
+FTP's use of multiple ports (control and data channels) frequently leads to firewall and Network Address Translation (NAT) traversal problems, increasing operational complexity and security risk.
+
+## Preventive Measures
+
+To mitigate the risks associated with file transfer operations, adopt the following security practices:
+
+### Avoid `ftplib.FTP` Entirely
+Never use plain FTP in production environments or for handling sensitive data, regardless of network segmentation or perceived isolation.
+
+### Use Secure Alternatives
+- **Prefer SFTP** (SSH File Transfer Protocol) using the `paramiko` library, which provides strong encryption and authentication through the SSH protocol.
+- **Alternatively, use FTPS** (FTP over TLS/SSL) via `ftplib.FTP_TLS` where SFTP is not available. Ensure that explicit TLS is enabled and certificate validation is enforced.
+
+### Enforce Encrypted Communication
+Verify that all authentication credentials and file transfers occur exclusively over encrypted channels. Reject any connection that does not support modern cryptographic standards.
+
+### Validate Third-Party Integrations
+Before integrating external services, confirm that they support secure protocols (SFTP or FTPS) and are configured to enforce encryption.
+
+### Apply Secure Credential Handling
+Store and manage credentials using secure mechanisms such as environment variables, dedicated secrets managers (e.g., HashiCorp Vault, AWS Secrets Manager), or encrypted configuration files. Never hard-code credentials in source code.
+
+## Example
+
+The following example demonstrates both insecure and secure approaches to file transfer using only Python's standard library:
+
+**INSECURE: Do not use this approach**
+```python
+from ftplib import FTP
+
+ftp = FTP("example.com")
+ftp.login("username", "password")  # Credentials sent in cleartext
+with open("file.txt", "rb") as f:
+    ftp.storbinary("STOR file.txt", f)
+ftp.quit()
+```
+
+**SECURE: Use FTPS with explicit TLS (standard library only)**
+
+```python
+from ftplib import FTP_TLS
+import ssl
+
+# Create FTPS connection with explicit TLS
+ftps = FTP_TLS("example.com")
+ftps.login("username", "password")
+
+# Force encryption for the data channel
+ftps.prot_p()
+
+# Optional: Enforce strict certificate validation
+ftps.ssl_context = ssl.create_default_context()
+ftps.ssl_context.check_hostname = True
+ftps.ssl_context.verify_mode = ssl.CERT_REQUIRED
+
+# Transfer file securely
+with open("file.txt", "rb") as f:
+    ftps.storbinary("STOR file.txt", f)
+
+ftps.quit()
+```
+
+### FTPS Configuration Best Practices
+
+When using `ftplib.FTP_TLS`, implement these additional security measures:
+
+```python
+import ssl
+from ftplib import FTP_TLS
+
+# Create a secure SSL context
+context = ssl.create_default_context()
+context.set_ciphers("ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20:!aNULL:!MD5:!DSS")
+context.options |= ssl.OP_NO_SSLv2 | ssl.OP_NO_SSLv3 | ssl.OP_NO_TLSv1 | ssl.OP_NO_TLSv1_1
+
+# Establish secure connection
+ftps = FTP_TLS("example.com", context=context)
+ftps.login("username", "password")
+ftps.prot_p()  # Critical: Force encrypted data channel
+
+# Verify server certificate matches hostname
+ftps.ssl_context.check_hostname = True
+
+# Transfer files with encryption
+with open("sensitive_data.txt", "rb") as f:
+    ftps.storbinary("STOR sensitive_data.txt", f)
+
+# Secure logout
+ftps.quit()
+```
+
+### Important FTPS Considerations
+
+- **Always call `prot_p()`**: Without this, your data channel remains unencrypted even if the control channel is secure.
+- **Certificate Validation**: Never disable certificate verification (avoid `ssl.CERT_NONE` in production).
+- **TLS Version**: Require TLS 1.2 or higher; disable older, vulnerable protocols.
+- **Cipher Suites**: Use only strong, modern cipher suites that provide forward secrecy.
+
+## Discussion
+
+The decision to avoid `ftplib.FTP` stems from fundamental protocol design flaws that cannot be mitigated through configuration or workarounds. While FTP remains in use due to legacy system requirements, modern security standards mandate encryption for all network communications.
+
+When SFTP is unavailable, FTPS with explicit TLS provides an acceptable alternative, provided that certificate validation is enforced and weak cryptographic ciphers are disabled. However, SFTP is generally preferred due to its simpler firewall traversal (single port), better integration with SSH infrastructure, and more comprehensive security features.
+
+Organizations should conduct regular audits to identify and remediate any lingering FTP usage. Good SAST scanning tools for Python detect imports of `ftplib.FTP` and flag them.
+
+## More Information
+
+- [CWE-319: Cleartext Transmission of Sensitive Information](https://cwe.mitre.org/data/definitions/319.html)
+- [Python `ftplib` Documentation](https://docs.python.org/3/library/ftplib.html)
+- [NIST SP 800-52: Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations](https://csrc.nist.gov/publications/detail/sp/800-52/rev-2/final)