Metadata-Version: 2.4
Name: secenvY
Version: 0.1.0
Summary: Gymnasium Environment for AI-driven Android Security Analysis, Dynamic Fuzzing, and Penetration Testing
Author: Android Security Agent Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/d4em0ny/android-security-agent
Project-URL: Repository, https://github.com/d4em0ny/android-security-agent.git
Project-URL: Issues, https://github.com/d4em0ny/android-security-agent/issues
Keywords: reinforcement-learning,gymnasium,android,security,penetration-testing,fuzzing,rag,dueling-dqn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: gymnasium>=0.29.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: torch>=2.0.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: google-genai>=0.1.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: websockets>=11.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# Android Security Environment (`secenvY`)

A high-performance Gymnasium environment and Reinforcement Learning brain layer for AI-driven Android penetration testing, automated vulnerability discovery, and dynamic security analysis.

---

## 🌟 Key Features

- **Standard Gymnasium `Discrete(8)` Action Space:**
  1. `0: TAP` (UI Exploration) — Tap clickable element / primary interactable.
  2. `1: TYPE_TEXT` (UI Exploration) — Type contextual credentials / input fields.
  3. `2: SCROLL` (UI Exploration) — Scroll down to reveal off-screen views.
  4. `3: BACK` (UI Exploration) — Press Android system back button.
  5. `4: INJECT_SQL_PAYLOAD` (Security Testing) — Fuzz active input fields / queries with SQL syntax.
  6. `5: START_ACTIVITY` (Security Testing) — Launch target exported Activity component directly via `am start`.
  7. `6: QUERY_PROVIDER` (Security Testing) — Query target Content Provider URI directly.
  8. `7: FINISH` (Lifecycle) — Conclude security audit session cleanly with completion rewards.
- **117-Dimensional Normalized Observation Tensor:** Comprehensive 17-group state representation bounded strictly in `[0.0, 1.0]` (`gymnasium.spaces.Box(low=0.0, high=1.0, shape=(117,), dtype=np.float32)`).
- **Sub-Millisecond Pipeline (< 1ms SLA):** Highly optimized validation, building, and encoding pipeline executing end-to-end in ~0.89 ms.
- **Multi-Tier RAG-Driven Reward Engine:** Objective reward formulation combining step efficiency, screen discovery bonuses, severity-weighted RAG evaluations, and anti-farming deduplication.
- **Production WebSocket Gateway & Server:** Synchronous `WebSocketSystemGateway` and standalone `server.py` FastAPI routing hub bridging RL environments, physical Android devices, and desktop dashboards.

---

## 📦 Installation

```bash
# Install from PyPI
pip install secenvY

# Or install from source in editable mode
git clone https://github.com/d4em0ny/android-security-agent.git
cd android-security-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

---

## 🚀 Quickstart Usage

```python
import gymnasium as gym
import secenvY

# 1. Create registered environment
env = gym.make("AndroidSecurityEnv-v0")

# 2. Reset environment to clean initial state
obs, info = env.reset(seed=42, options={"pkg": "com.vulnerable.bank"})
print(f"Observation Shape: {obs.shape}")  # (117,)
print(f"Action Space:      {env.action_space}") # Discrete(8)
print(f"Action Mask:       {info['action_mask']}")

# 3. Step through episode
terminated = False
truncated = False
while not (terminated or truncated):
    action_mask = info.get("action_mask")
    # Sample or select discrete action (0..7)
    action = env.action_space.sample(mask=action_mask)
    obs, reward, terminated, truncated, info = env.step(action)
    print(f"Step {info['step']} -> Reward: {reward:+.3f} (Terminated: {terminated})")

env.close()
```

---

## 🧪 Running Tests & Verification

```bash
# Run all unit and integration tests
pytest tests/ -v

# Run performance benchmark (< 5ms SLA verification)
pytest tests/test_pipeline_performance.py -v -s

# Run static type checker
mypy secenvY/ server.py main.py --config-file mypy.ini
```

---

## 📄 License

Apache-2.0 License.
