Metadata-Version: 2.4
Name: algo-secure
Version: 0.1.3
Summary: Semantic security scanner for Algorand smart contracts and workflows
Author: Algosec Maintainers
License-Expression: MIT
Project-URL: Homepage, https://github.com/akprajwal/algo
Project-URL: Repository, https://github.com/akprajwal/algo
Project-URL: Issues, https://github.com/akprajwal/algo/issues
Keywords: algorand,security,cli,teal,defi
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.3
Requires-Dist: rich>=13.7.1
Requires-Dist: pyteal>=0.27.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: py-algorand-sdk>=2.7.0
Provides-Extra: ai
Requires-Dist: google-generativeai>=0.8.5; extra == "ai"
Requires-Dist: google-genai>=1.71.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Requires-Dist: ruff>=0.7.0; extra == "dev"
Dynamic: license-file

# AlgoSec (A Secure)

AlgoSec is a semantic security scanner and runtime decision assistant for Algorand smart contracts.

It supports static contract analysis, on-chain checks, AI-assisted risk narratives, contract auto-remediation, and API-based policy gating.

## 1) What AlgoSec does today

### Contract scanning (TEAL + PyTeal)
- Scans files or folders containing `.teal` / `.py` contracts.
- Normalizes PyTeal patterns (`approval_program` / `clear_state_program`) before analysis.
- Runs semantic checks for common exploit paths:
  - missing `RekeyTo == ZeroAddress`
  - missing `CloseRemainderTo == ZeroAddress`
  - missing `AssetCloseTo == ZeroAddress`
  - unguarded update/delete/admin paths
  - unsafe `Gtxn` assumptions without strict group validation
  - missing argument-bound checks
  - state mutation without sender/role authorization

### Scoring and risk output
- Computes `security_score`, `risk_score`, `grade`, and deploy verdict.
- Exit code is non-zero when findings/errors exist (CI-friendly behavior).

### Reports
- Console dashboard (visual)
- JSON
- Markdown
- SARIF
- HTML (expanded analytics + charts)

### On-chain and indexer analysis
- Scan deployed app by `app_id`
- Scan account risk posture
- Scan ASA metadata/configuration
- Scan transaction streams for anomalies

### AI-assisted workflow
- `ai-run`: scan + simulate + policy decision + explanation artifacts.
- Works in two modes:
  - **deterministic mode** (always available; no key required)
  - **Gemini narrative mode** (optional; enabled when API key is available)

### Auto-fix workflow
- `fix-contract` applies hardened guard patterns to vulnerable PyTeal contracts.
- Optional post-fix verification scan (`--verify`).

### Entitlement / premium support
- `premium-status` supports ASA-balance mode and subscription-app mode.
- Testnet deploy commands are **dry-run by default** for safety.

## 2) Installation

### Standard install
```bash
pip install algo-secure
```

### With Gemini SDKs
```bash
pip install "algo-secure[ai]"
```

### Development install
```bash
pip install -e .
```

## 3) Quick start

```bash
# Home UI
algosec

# Core scan
algosec analyze ./contracts

# Export html report
algosec scan ./contracts -f html -o report.html

# Compare two versions
algosec diff ./contracts_old ./contracts_new

# Auto-fix a vulnerable contract
algosec fix-contract examples/incoming_contracts/random_user_contract.py --verify
```

Aliases: `algosec`, `alg`, `aplussec`.

## 4) Command groups

### Static and project scan
- `scan`, `alg_scan`, `analyze`
- `stats`
- `diff`

### On-chain/indexer scan
- `scan-deployed-app`, `alg_scan_deployed_app`
- `scan-account`, `alg_scan_account`
- `scan-asset`, `alg_scan_asset`
- `scan-transactions`, `alg_scan_transactions`

### Testing
- `test-pyteal`, `alg_test_pyteal`

### AI and remediation
- `ai-status`
- `ai-run`, `alg_ai_run`
- `fix-contract`, `alg_fix_contract`

### Entitlement and deploy
- `premium-status`
- `deploy-token-registry-testnet`
- `deploy-subscription-testnet`

### API server
- `serve`

## 5) AI behavior (important)

AlgoSec is designed to work on any system even without LLM credentials.

- If no Gemini key/sdk is available, `ai-run` still executes using deterministic reasoning (`narrative_provider=deterministic`).
- If Gemini is available, narrative generation switches to `narrative_provider=gemini`.

Gemini key lookup order:
1. `ALGOSEC_GEMINI_API_KEY`
2. `GEMINI_API_KEY`
3. `GOOGLE_API_KEY`

Optional one-shot override:
```bash
algosec ai-status --gemini-api-key "<key>"
```

## 6) Security and secret handling

- No API key is hardcoded in source.
- Auth signing secret does **not** default to a fixed insecure string.
- If `ALGOSEC_AUTH_SECRET` is absent, runtime uses an ephemeral in-memory secret.
- Recommendation for production API deployments:
  - set `ALGOSEC_AUTH_SECRET`
  - set `ALGOSEC_REQUIRE_API_KEY=1`
  - set `ALGOSEC_API_KEY`

## 7) API surface

Primary routes include:
- `/health`
- `/scan`
- `/simulate`
- `/safe_execute`
- `/agent/run`
- `/auth/challenge`
- `/auth/verify`
- `/auth/me`

## 8) Packaging and release status

- `pyproject.toml` is configured for setuptools build.
- Wheel + sdist build is validated (`python -m build`, `twine check`).
- PyPI publishing workflow is present in [.github/workflows/release.yml](.github/workflows/release.yml).

## 9) License

MIT — see [LICENSE](LICENSE).
