flutterguard_cli 0.1.0

Developer-friendly FlutterGuard CLI for CI/CD and local security analysis of Flutter/Android apps.

FlutterGuard CLI

Developer-friendly CLI for automated security analysis of Flutter/Android apps

Integrate FlutterGuard security scanning directly into your CI/CD pipeline or use locally for rapid feedback during development.

Features

✨ Automated Security Analysis

• 🔍 Detects debuggable builds
• 🔐 Identifies hardcoded secrets (API keys, tokens, passwords)
• 🚨 Checks for root access patterns
• 📜 Analyzes dangerous permissions
• 🔒 Validates SSL/TLS certificate configurations

⚡ CI/CD Ready

• Zero-config operation with environment variables
• --wait mode for synchronous pipeline integration
• Meaningful exit codes for automated workflows
• Detailed JSON output for custom processing

🧪 Thoroughly Tested

• 37 unit and integration tests
• Mock HTTP client for reliable testing
• Command validation and error handling

dart run bin/flutterguard.dart --help

Quick Start

Installation

Install from pub.dev (recommended):

dart pub global activate flutterguard_cli
flutterguard --help

Install from source:

git clone https://github.com/flutter-spy/flutter-spy.git
cd flutter-spy/cli
dart pub get
dart pub global activate --source path .
flutterguard --help

Get Your API Key

1. Sign up at FlutterGuard
2. Navigate to your dashboard
3. Generate an API key

Run Your First Scan

export FG_API_KEY="your-api-key-here"
flutterguard scan --file path/to/your-app.apk --wait

Configuration

Set these environment variables or pass as command flags:

Variable	Required	Default	Description
FG_API_KEY	Yes	-	API key from your FlutterGuard dashboard
FG_API_BASE_URL	No	https://api.flutterguard.dev/api/v1/api/	Override API endpoint

Using environment variables:

export FG_API_KEY="your-api-key"
export FG_API_BASE_URL="https://api.flutterguard.dev/api/v1/api/"

Using command-line flags:

flutterguard scan --file app.apk --api-key "your-api-key" --base-url "https://custom-api.com"

Testing

Run the test suite:

dart test

The test suite includes:

• Unit tests (test/client_test.dart): Tests for the API client with mocked HTTP responses
• Integration tests (test/commands_test.dart): Tests for CLI command parsing and validation

All tests should pass before deploying or publishing the CLI.

Commands

scan - Analyze an APK

Upload and analyze an APK file for security vulnerabilities.

flutterguard scan --file app.apk

Options:

• --file (required): Path to the APK file
• --wait: Wait for analysis to complete (synchronous mode)
• --interval: Polling interval in seconds (default: 15)
• --timeout: Maximum wait time in seconds (default: 300)

Examples:

# Quick async scan
flutterguard scan --file app-debug.apk

# Wait for results (useful in CI/CD)
flutterguard scan --file app-release.apk --wait --timeout 600

# Custom polling interval
flutterguard scan --file app.apk --wait --interval 10

status - Check Scan Status

Check the status and results of a previous scan.

flutterguard status --id <analysis_id>

Options:

• --id (required): Analysis ID returned from the scan command

Example:

flutterguard status --id abc123-def456-ghi789

list - View All Scans

List all scans for your account with pagination.

flutterguard list

Options:

• --limit: Number of results to return (default: 20)
• --offset: Number of results to skip (default: 0)

Examples:

# List first 20 scans
flutterguard list

# List next 20 scans
flutterguard list --offset 20

# List 50 scans
flutterguard list --limit 50

CI/CD Integration

GitHub Actions

Add this workflow after building your APK:

name: Security Scan

on: [push, pull_request]

jobs:
  flutterguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Dart
        uses: dart-lang/setup-dart@v1
        with:
          sdk: stable

      - name: Install FlutterGuard CLI
        run: |
          cd cli
          dart pub get
          dart pub global activate --source path .

      - name: Build APK
        run: |
          # Your build commands here
          flutter build apk --debug

      - name: Run Security Scan
        env:
          FG_API_KEY: ${{ secrets.FG_API_KEY }}
        run: |
          APK_PATH=$(find . -name "*debug*.apk" | head -n 1)
          flutterguard scan --file "$APK_PATH" --wait --timeout 600

GitLab CI

stages:
  - build
  - scan

flutterguard_scan:
  stage: scan
  image: dart:stable
  before_script:
    - apt-get update && apt-get install -y git
    - cd cli
    - dart pub get
    - dart pub global activate --source path .
  script:
    - APK_PATH=$(find . -name "*.apk" | head -n 1)
    - flutterguard scan --file "$APK_PATH" --wait --timeout 600
  variables:
    FG_API_KEY: "$FG_API_KEY"
  only:
    - main
    - merge_requests

CircleCI

version: 2.1

jobs:
  security-scan:
    docker:
      - image: google/dart:latest
    steps:
      - checkout
      - run:
          name: Install CLI
          command: |
            cd cli
            dart pub get
            dart pub global activate --source path .
      - run:
          name: Run Scan
          command: |
            APK_PATH=$(find . -name "*.apk" | head -n 1)
            flutterguard scan --file "$APK_PATH" --wait --timeout 600
          environment:
            FG_API_KEY: $FG_API_KEY

Exit Codes

The CLI returns meaningful exit codes for automation:

Code	Meaning
0	Success - scan completed without critical issues
1	Failure - validation error, API error, or critical vulnerabilities found

In CI/CD pipelines:

• Exit code 1 will fail your build pipeline
• Use --wait to get synchronous results
• Configure your pipeline to continue or fail based on exit code

Testing

Run the comprehensive test suite:

dart test

Test Coverage:

• ✅ 37 passing tests
• ✅ Unit tests for API client with mocked HTTP responses
• ✅ Integration tests for CLI command parsing and validation
• ✅ Error handling and edge cases

All tests should pass before deploying or publishing the CLI.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (dart test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• 🌐 FlutterGuard Website
• 📚 Documentation
• 🐛 Report Issues
• 💬 Get Support

Support

Need help? Contact us:

• 📧 Email: [e-mail]
• 💬 Discord: Join our community
• 🐦 Twitter: @FlutterGuard

---

Made with ❤️ by the FlutterGuard team