refactoring-agent 3.12.7
Security Remediation Agent for Python codebases
License: MIT
Requires Python: >=3.9
Keywords: refactoring, security, legacy, openai, llm, automation

# 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).