algo-secure 0.1.2

Semantic security scanner for Algorand smart contracts and workflows

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

pip install algo-secure

With Gemini SDKs

pip install "algo-secure[ai]"

Development install

pip install -e .

3) Quick start

# 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:

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.

9) License

MIT — see LICENSE.