refactoring-agent 3.12.5

Security Remediation Agent for Python codebases

Refactoring Agent – Security Remediation for Legacy Python

Refactoring Agent is a command-line tool that scans your Python codebase for legacy patterns and security risks, and optionally asks an LLM to propose safe, modern fixes.

It is built for teams who are migrating large, messy, “battle-tested” codebases and want:

• Static checks for legacy constructs (e.g. raw_input, old print statements)
• Security scanning for dangerous APIs (eval, exec, os.system, pickle)
• Optional AI-based refactoring suggestions (OpenAI, Ollama, or a mock provider)
• CI-friendly CLI and GitHub Actions integration

---

Features

🛡️ Security Scanning (Enterprise Grade)

Refactoring Agent goes beyond simple linting. It proactively hunts for Critical Vulnerabilities (OWASP Top 10 vectors):

ID	Severity	Description
security_eval	Critical	Detects arbitrary code execution via eval().
security_exec	Critical	Detects dynamic code execution via exec().
security_os_system	Critical	Flags os.system() which is vulnerable to shell injection.
security_subprocess_shell	Critical	Detects subprocess.Popen(..., shell=True) – a common RCE vector.
security_pickle_untrusted	Critical	Blocks pickle.load() on untrusted data (Insecure Deserialization).
security_insecure_random	Major	Warns about using random for secrets/tokens (suggests secrets module).

🤖 AI-assisted Refactoring & Auto-Fix

The tool can automatically fix issues using LLMs. It supports two modes:

1. Interactive Mode (Default)

Best for local development. The tool shows you a diff for every file and asks for confirmation. ```bash refactor-agent check . --ai-fix ``` Output: Shows diff, then asks Apply this fix to src/main.py? [y/n].

2. Non-Interactive / CI Mode (--yes)

Best for CI/CD pipelines or when you trust the AI. ```bash refactor-agent check . --ai-fix --yes ``` Behavior: Applies all fixes automatically without prompts.

Note: If you run --ai-fix in a CI environment (no TTY) without --yes, the tool will fail with an error to prevent hanging.

---

Installation

Install from PyPI: ```bash pip install refactoring-agent ```

Quickstart

Initialize configuration: ```bash refactor-agent init ```

Scan the current directory: ```bash refactor-agent check . ```

Generate an HTML report: ```bash refactor-agent check . --html-report report.html ```

Using AI Suggestions

OpenAI provider

```bash export RA_LLM_PROVIDER="openai" export OPENAI_API_KEY="your-openai-key"

refactor-agent check demo_legacy --ai-fix --dry-run ```

Ollama provider (Local LLM)

```bash export RA_LLM_PROVIDER="ollama" export RA_LLM_MODEL="llama3"

refactor-agent check demo_legacy --ai-fix --dry-run ```

Configuration

Refactoring Agent allows fine-grained control over rules via pyproject.toml.

```toml [tool.refactoring-agent.rules]

Strict security

security_eval = "error" security_subprocess_shell = { mode = "error", severity = "critical" }

Relaxed legacy checks (warnings only)

legacy_print = "warn" ```

GitHub Action example

```yaml name: Security Scan on: [push, pull_request] jobs: refactor-agent: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: { python-version: "3.11" } - run: pip install refactoring-agent - name: Run Scan & Auto-Fix (Dry Run) run: | refactor-agent check .
--ai-fix --dry-run
--provider openai --api-key ${{ secrets.OPENAI_KEY }}
--html-report report.html ```

Exit Codes & CI Integration

Refactoring Agent is designed to be CI-friendly.

Exit Code	Meaning
0	Success. No blocking issues found (or --soft-fail enabled).
1	Failure. Critical or Major security issues found in error mode.
2	Internal Error. Bad arguments, missing dependencies, or crash.

Blocking vs Non-Blocking

By default, an issue breaks the build (Exit 1) if:

1. Rule mode is "error" (default for security rules).
2. Severity is critical or major.

Soft-Fail Mode (--soft-fail)

If you want to run the scan in CI to generate reports (e.g. SARIF/HTML) without breaking the build, use:

```bash refactor-agent check . --html-report report.html --soft-fail ```

In this mode, the tool will output all findings but always exit with code 0 (unless an internal crash occurs).