From 9bb1630c1d034e75679e391f3ecb454563fb5c9a Mon Sep 17 00:00:00 2001 From: Samuel Chen <119898205+sacchen@users.noreply.github.com> Date: Sat, 11 Apr 2026 03:27:48 -0700 Subject: [PATCH] Release v0.2.7: changelog and remove redteam report Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 11 ++++++++ REDTEAM_REPORT.md | 67 ----------------------------------------------- 2 files changed, 11 insertions(+), 67 deletions(-) delete mode 100644 REDTEAM_REPORT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c1f3eeb..1a76877 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## 0.2.7 - 2026-04-11 + +- Add `--no-wa` flag to suppress WolframAlpha fallback hints (useful for offline or privacy-sensitive workflows); also settable inline in the REPL. +- Guard `solve()` against matrix-style keyword arguments (`solve(A=..., b=...)`) with a clear error and redirect hint to `linalg solve` or `msolve(A, b)`. +- Expand linalg subcommands: `eig`, `nullspace`, `rank` now available alongside existing `solve`, `rref`, `det`, `inv`. +- Broaden SymPy symbol allowlist so more built-in functions and constants are available without manual import. +- Unify one-shot and REPL shortcut dispatch so edge-case behavior is consistent across both modes. +- Improve error hint coverage: deterministic fallback hints for unknown errors, better `solve()` ambiguity diagnostics, `zoo` hint for complex infinity results. +- Extract linalg dispatch to `linalg.py` (internal refactor; no behavior change). +- Bump `pygments` to 2.20.0 (CVE-2026-4539). + ## 0.2.6 - 2026-02-23 - Add symbolic-first growth guardrails for huge integer powers, exponent towers, and large factorial inputs. diff --git a/REDTEAM_REPORT.md b/REDTEAM_REPORT.md deleted file mode 100644 index b3b2cc7..0000000 --- a/REDTEAM_REPORT.md +++ /dev/null @@ -1,67 +0,0 @@ -# Redteam Security and Architecture Report: `phil` (SymPy CLI Calculator) - -**Target Repository:** `sacchen/phil` (Local path: `/Users/goddess/foundry/sandbox/calc`) -**Focus Areas:** Accuracy, Relevance, Style, and Security Posture -**Date:** April 11, 2026 - -## Executive Summary - -`phil` is a sophisticated command-line interface (CLI) calculator that leverages the power of Python's `SymPy` library to provide Computer Algebra System (CAS) capabilities directly in the terminal. This redteam analysis evaluates the application's resilience against common vulnerabilities associated with symbolic computation and mathematical parsing—specifically Arbitrary Code Execution (ACE) and Denial of Service (DoS) via resource exhaustion. - -The codebase demonstrates an exceptionally high level of maturity. The developers have anticipated the core vulnerabilities of `eval`-based symbolic evaluation and implemented rigorous, Abstract Syntax Tree (AST)-level defenses. While highly secure and well-architected, its primary weaknesses lie in the inherent mathematical ambiguities of its "relaxed" parsing mode and the operational security (OpSec) implications of its fallback mechanisms. - ---- - -## 1. Accuracy & Functional Security - -Mathematical parsers in Python that wrap `SymPy` are typically fraught with two major vulnerabilities: **Arbitrary Code Execution (ACE)** and **Denial of Service (DoS)**. `phil` implements robust defenses against both. - -### A. Arbitrary Code Execution (ACE) Mitigation -* **The Threat:** SymPy’s `parse_expr` function internally utilizes Python's `eval()`. Without strict sanitization, a malicious user could input a string like `__import__('os').system('rm -rf /')`, leading to catastrophic system compromise. -* **The Defense:** The application successfully neutralizes this threat through a multi-layered defense-in-depth approach: - 1. **Lexical Scrubbing:** It scrubs dangerous characters via `BLOCKED_PATTERN = re.compile(r"(__|;|\n|\r)")`, breaking most introspection attempts before they reach the parser. - 2. **Namespace Isolation (The Gold Standard):** Instead of relying solely on string sanitization (which is prone to bypasses), `phil` enforces a strict namespace. It calls `parse_expr` with `global_dict=GLOBAL_DICT`, explicitly overriding Python's `__builtins__` with an empty dictionary. It exclusively whitelists safe, mathematical operations (e.g., `Add`, `Mul`, `Integer`, `Float`). -* **Verdict:** **Highly Secure.** The team has properly sandboxed the evaluation environment, making code injection virtually impossible through standard CLI usage. - -### B. Resource Exhaustion / DoS (Advanced Mitigation) -* **The Threat:** Symbolic engines will happily consume unbounded memory or CPU time if asked to calculate massive numbers (e.g., `10**10**10`) or massive factorials (e.g., `10000000!`). This causes the application to hang indefinitely. -* **The Defense:** Instead of relying on crude and often unreliable multi-threading timeouts, the author implements brilliant AST-level inspections *before* mathematical evaluation: - * **Pre-Evaluation Scanning:** Functions like `_validate_factorial_literals` and `_raise_if_huge_factorial_call` scan the pre-evaluated expression tree (created safely via `evaluate=False`) for factorial arguments exceeding a safe `MAX_FACTORIAL_N`. - * **Algebraic Cancellation Check (`_reduce_huge_integer_powers`):** This is a standout feature. It parses the expression safely, finds huge integer powers, and substitutes them with `Dummy` symbols. It then runs SymPy's `simplify()`. If the huge power algebraically cancels out (e.g., `(10**10**10) / (10**10**10)`), it successfully returns `1`. If the dummy symbol remains after simplification, it halts and throws a `ValueError` rather than attempting to materialize the massive integer in memory. -* **Verdict:** **Highly Accurate & Resilient.** The edge-case handling for structural mathematics is exceptionally robust and well-engineered. - -### C. Implicit Multiplication Ambiguity (The Primary Weakness) -* **The Threat:** `phil` heavily advertises "relaxed parsing," leveraging SymPy’s `implicit_multiplication_application` transformations to allow inputs like `2x` instead of `2*x`. -* **The Problem:** The ambiguity of expressions like `x y` (is it a single variable `xy` or `x * y`?) is a computationally unsolvable problem without strict user intent. While convenient, the parser's heuristics occasionally guess wrong, which can silently alter the user's intended mathematical equation, leading to incorrect results without throwing an error. -* **Verdict:** **Moderate Accuracy Risk.** While the "strict" mode circumvents this, the default "relaxed" mode sacrifices mathematical exactness for user convenience—a classic "foot-gun" in production calculator usage. - ---- - -## 2. Relevance and Operational Security (OpSec) - -* **The Target Audience:** The tool perfectly bridges the gap between lightweight calculators (like `bc` or `qalc`) and heavy computational environments (like Jupyter notebooks). It brings rich formatting (LaTeX, pretty-printing) to the terminal. -* **The "WolframAlpha Fallback" (Privacy Leak):** When the local SymPy engine fails to parse or simplify an expression, the CLI provides a formatted fallback URL to WolframAlpha. - * *Critique:* While highly relevant for User Experience (UX) and "failing gracefully", this mechanism introduces a significant privacy and OpSec risk. Users might implicitly trust the offline, local nature of a terminal CLI. Clicking the fallback URL transmits their exact equation structure (which could contain proprietary algorithms, financial figures, or sensitive data) to a third-party commercial server. -* **Dependency Bloat:** Requiring a full Python environment and the massive `SymPy` library just to do quick terminal math makes it somewhat heavy for users who only need simple arithmetic. - ---- - -## 3. Style & Maintainability - -* **Test Suite Rigor:** The project boasts an immaculate and comprehensive `pytest` suite. Local test runs indicate 282 passing tests heavily utilizing hypothesis/regression structures. Critically, the tests explicitly verify the safety boundaries (e.g., `test_cli_huge_factorial_fails_fast_with_hint`, `test_cli_safety_guards_blocked_and_too_long_input`), proving the security guardrails are maintained features, not happy accidents. -* **Architecture & Separation of Concerns:** The codebase elegantly separates CLI logic (`cli.py`), mathematical routing (`core.py`, `linalg.py`, `ode.py`), and presentation (`render.py`). This strict separation allows the underlying CAS to be swapped out or upgraded without breaking the terminal UI. -* **Code Quality:** The Python code is thoroughly type-hinted and relies on modern idioms. Error handling is proactive, intercepting generic Python/SymPy crashes and translating them into user-friendly diagnostics with actionable recovery hints. - ---- - -## 4. Key Takeaways - -### For Users: -1. **Trust the Sandbox:** The tool is highly secure against code injection. You can safely run it locally without fear of accidental system execution. -2. **Beware Relaxed Parsing:** If performing critical engineering or financial calculations, explicitly use `*` for multiplication or run the tool in strict mode to avoid silent parsing errors. -3. **Mind Your OpSec:** Be cautious when using the WolframAlpha fallback links if your equations contain sensitive or proprietary data, as this transmits your input over the internet. - -### For Developers/Maintainers: -1. **Exemplary Defensive Programming:** The use of AST pre-parsing (`evaluate=False`) combined with Dummy symbol cancellation checks is a masterclass in preventing DoS in symbolic computation. This pattern should be documented and celebrated. -2. **Consider an Opt-in Telemetry/Network Model:** The WolframAlpha link generation should ideally come with a first-time warning or require an explicit flag to ensure users are aware their local CLI session might bridge to the web. -3. **Dependency Alternatives:** While SymPy is powerful, exploring lighter-weight parsing libraries or compiled extensions (like Rust bindings) in the future could drastically reduce the installation footprint. \ No newline at end of file