Skip to content

aws-samples/sample-Webaccess-KiroCLI

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
backend
backend
 
 
docs
docs
 
 
frontend
frontend
 
 
image
image
 
 
nginx
nginx
 
 
scripts
scripts
 
 
.gitignore
.gitignore
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

KiroCLI Platform

A secure, browser-based platform for managing Kiro CLI terminal sessions — powered by AWS IAM Identity Center SSO, with zero credential exposure.

Current Version: 1.1.2 | Changelog | v1.1 Deployment Guide

SSO Login

What's New in v1.1.2

v1.1.2 focuses on security hardening based on GitLab code security scanning:

  • 🔒 26+ Security Scan Fixes — Resolved all findings from 3 rounds of GitLab SAST/Secret Detection
  • 📦 Dependency Upgrades — python-jose → PyJWT, asyncssh 2.19.0, python-multipart 0.0.22
  • 🛡️ Command Execution Hardening — Executable allowlist for subprocess calls
  • 🔐 Secret Detection Exclusions — .gitlab/secret-detection-ruleset.toml for known false positives
  • 🧩 Frontend Dependency Lock — Exact version pinning to prevent supply chain attacks

See the full changelog for details.

What's New in v1.1

v1.1 introduces enterprise-grade security features and operational improvements:

  • 🔒 IP Whitelist - Restrict access by IP/CIDR ranges with dynamic Nginx configuration
  • 📊 Audit Logging - Track all security events with CSV export for compliance
  • 🚨 Alert System - Real-time anomaly detection with AWS SNS notifications
  • 🔄 Refresh Tokens - Long-lived sessions with automatic rotation and revocation
  • 📱 Device Fingerprinting - Track and manage trusted devices per user
  • 🔌 Force Logout - Remotely terminate user sessions across all devices
  • 🔐 Nginx-Proxied Terminals - Enhanced security with JWT-based auth_request
  • 🔑 AWS Secrets Manager - Centralized secret management with rotation detection
  • ⏱️ Real-time Duration - Live session timers with proper timezone handling
  • 📈 Startup Progress - Visual feedback during terminal launch

See the full changelog for details.

Why KiroCLI Platform?

Managing Kiro CLI across a team is painful. Developers need to handle AWS credentials, manage local installations, and deal with session sprawl. KiroCLI Platform solves this by centralizing access through a secure web interface.

Challenge Traditional Approach KiroCLI Platform
Authentication Distribute AK/SK to every developer SSO login via AWS IAM Identity Center — no credentials to manage
Access control Manual IAM policy per user Role-based groups with per-user session quotas
Session security Direct CLI access, no audit trail Random-token URLs + TLS encryption + session logging
Concurrent users One CLI per machine Up to 100 concurrent browser-based sessions per instance
Credential rotation Update AK/SK on every machine Centralized — rotate once in IAM Identity Center

Key Security Features

  • No AK/SK distribution — Users authenticate via AWS IAM Identity Center (SAML 2.0). No AWS access keys are ever shared with end users.
  • Random-token terminal URLs — Each Gotty session gets a 16-character cryptographically random URL token (e.g. /abcd1234efgh5678/). Guessing a session URL is computationally infeasible.
  • TLS encryption — All terminal traffic between the browser and Gotty is encrypted over HTTPS/WSS. No plaintext terminal data on the wire.
  • Session isolation — Each user gets their own Gotty process. Sessions are fully isolated and automatically cleaned up on idle timeout.
  • JWT-based API auth — Backend APIs are protected with short-lived JWT tokens (8-hour expiry by default).

Features

Core Features (v1.0)

  • SSO Authentication via AWS IAM Identity Center (SAML 2.0)
  • Browser-based Terminal powered by Gotty + Kiro CLI
  • Session Management — start, monitor, and close terminal sessions
  • User & Group Management with role-based access control
  • Concurrent Sessions — supports up to 100 simultaneous terminal sessions
  • Auto Cleanup — idle sessions are automatically terminated
  • System Monitoring dashboard with real-time metrics

Security Features (v1.1)

  • IP Whitelist — Restrict access by IP/CIDR ranges (admin-configurable)
  • Audit Logging — Comprehensive event tracking with CSV export
  • Alert System — Anomaly detection (session burst, login failures, multi-IP, off-hours)
  • Refresh Tokens — Long-lived sessions with automatic rotation
  • Device Fingerprinting — Track and manage trusted devices
  • Force Logout — Remote session termination by administrators
  • Nginx-Proxied Terminals — JWT-based authentication for terminal access
  • AWS Secrets Manager — Centralized secret management

Screenshots

Session Management

Session Management

Browser Terminal

Web Terminal Session

Architecture

Browser → Nginx (port 3000) → FastAPI Backend (127.0.0.1:8000)
                                      ↓
                    ┌─────────────────┴──────────────────┐
                    │                                     │
                    ▼                                     ▼
            Gotty Sessions                        SQLite Database
       (127.0.0.1:7861–7960, TLS)              (14 tables, v1.1)
       [Nginx auth_request proxy]
                    ↓
                kiro-cli

v1.1 Changes:

  • Gotty now binds to 127.0.0.1 (not 0.0.0.0) for security
  • Terminal access via Nginx reverse proxy with JWT authentication
  • No direct public access to Gotty ports (7860-7960 no longer needed in Security Group)
  • Dynamic route configuration using Nginx map directive

All components run on a single EC2 instance. No external dependencies beyond AWS IAM Identity Center (and optionally AWS SNS + Secrets Manager for v1.1 features).

Prerequisites

  • AWS EC2 instance running Ubuntu 22.04 (recommended: t3.medium or larger)
  • AWS IAM Identity Center configured with a SAML application
  • Kiro CLI installed and configured on the EC2 instance (see installation steps below)
  • EC2 Security Group inbound rules:
Port Protocol Source Purpose Version
22 TCP Your IP SSH v1.0+
3000 TCP 0.0.0.0/0 Web UI (Nginx) v1.0+

v1.1 Security Improvement: Ports 7860-7960 are no longer required. Gotty now binds to 127.0.0.1 and is accessed via Nginx proxy on port 3000. You can remove these ports from your Security Group for improved security.

Optional (v1.1):

  • AWS SNS Topic for alert notifications
  • AWS Secrets Manager for centralized secret management

Installing Kiro CLI (Required Before Deployment)

Important: Kiro CLI must be installed and configured BEFORE running the deployment script. The installation process requires interactive configuration that cannot be automated.

Installation Steps

  1. Update system and install dependencies:
# Update package lists
sudo apt update

# Install required dependencies for Kiro CLI
sudo apt install -y libayatana-appindicator3-1 libwebkit2gtk-4.1-0 libgtk-3-0
  1. Download and install Kiro CLI:
# Download the latest Kiro CLI package
wget https://desktop-release.q.us-east-1.amazonaws.com/latest/kiro-cli.deb

# Install the package
sudo dpkg -i kiro-cli.deb

# Fix any remaining dependency issues (if needed)
sudo apt-get install -f -y

# Clean up
rm kiro-cli.deb
  1. Verify installation:
kiro-cli --version
  1. Configure Kiro CLI:
# Run Kiro CLI to complete initial configuration
kiro-cli

# Follow the interactive prompts to:
# - Authenticate with your AWS credentials
# - Configure default settings
# - Complete any required setup steps
  1. Verify Kiro CLI is working:
# Test that Kiro CLI can execute commands
kiro-cli --help

Note: The deployment script (install.sh) will verify that Kiro CLI is installed and accessible. If Kiro CLI is not found, the script will exit with an error message.

Configuring AWS IAM Identity Center (Required Before Deployment)

Important: You must configure AWS IAM Identity Center BEFORE running the installation script. The script will prompt you for configuration values that you'll obtain from IAM Identity Center.

Quick Configuration Checklist

Before running the installation script, complete these steps in AWS IAM Identity Center:

  1. ✅ Create users with valid email addresses
  2. ✅ Create groups and assign users
  3. ✅ Create SAML application with correct URLs:
    • Application ACS URL: http://<YOUR_IP_OR_DOMAIN>:3000/api/v1/auth/saml/callback
    • Application SAML audience: http://<YOUR_IP_OR_DOMAIN>:3000/api/v1/auth/saml/metadata
  4. ✅ Configure attribute mappings:
    • Subject: ${user:email} (format: emailAddress)
    • email: ${user:email} (format: unspecified)
    • groups: ${user:groups} (format: unspecified)
  5. ✅ Assign users/groups to the application
  6. ✅ Collect configuration values:
    • SAML IDP Entity ID
    • SAML IDP SSO URL
    • SAML IDP X509 Certificate
    • IAM Identity Store ID
    • AWS Region

Detailed Configuration Guide

For step-by-step instructions with screenshots and troubleshooting, see:

📖 IAM Identity Center Configuration Guide

This guide covers:

  • Creating users and groups
  • Creating and configuring the SAML application
  • Setting up attribute mappings
  • Collecting all required configuration values
  • Common troubleshooting scenarios

EC2 IAM Role

The EC2 instance needs an IAM Role with permissions for both platform features and Kiro-CLI operations.

Understanding IAM Role Requirements

Important: The EC2 IAM Role serves two purposes:

  1. Platform Features - Permissions for the platform itself (IAM Identity Center sync, Secrets Manager, SNS alerts)
  2. Kiro-CLI Operations - Permissions for AWS operations that users execute through Kiro-CLI in terminal sessions

The platform's SAML authentication only controls who can log in. All AWS operations performed through Kiro-CLI use the EC2's IAM Role credentials. Therefore, you must grant the EC2 Role sufficient permissions based on what AWS resources your users need to manage.

Required Permissions

1. Platform Base Permissions (Required)

For IAM Identity Center Sync (syncing users and groups into the local database):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "IdentityStoreReadOnly",
      "Effect": "Allow",
      "Action": [
        "identitystore:ListUsers",
        "identitystore:ListGroups",
        "identitystore:ListGroupMembershipsForMember",
        "identitystore:DescribeGroup"
      ],
      "Resource": "*"
    }
  ]
}

For AWS Secrets Manager (optional, v1.1):

{
  "Sid": "SecretsManagerRead",
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue",
    "secretsmanager:DescribeSecret"
  ],
  "Resource": "arn:aws:secretsmanager:*:*:secret:kirocli-platform-*"
}

For SNS Alerts (optional, v1.1):

{
  "Sid": "SNSPublish",
  "Effect": "Allow",
  "Action": [
    "sns:Publish"
  ],
  "Resource": "arn:aws:sns:*:*:kirocli-alerts"
}

2. Kiro-CLI Operational Permissions (Choose Based on Use Case)

Users execute Kiro-CLI commands through terminal sessions. The EC2 IAM Role determines what AWS operations they can perform.

Option A: Full Administrative Access (recommended for production operations teams)

Attach the AWS managed policy: AdministratorAccess

Use when users need to:

  • Manage all AWS services (EC2, S3, RDS, Lambda, etc.)
  • Create, modify, and delete resources
  • Perform complete infrastructure operations

Option B: Service-Specific Access (recommended for limited scope)

Attach specific AWS managed policies based on required services:

  • AmazonEC2FullAccess - EC2 instance management
  • AmazonS3FullAccess - S3 bucket operations
  • AmazonRDSFullAccess - RDS database management
  • AWSLambda_FullAccess - Lambda function management
  • CloudWatchFullAccess - CloudWatch monitoring
  • IAMFullAccess - IAM management (use with caution)

Option C: Custom Minimal Permissions (recommended for security-sensitive environments)

Create a custom policy with only the specific actions needed. Example for read-only EC2 access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "KiroCLIEC2ReadOnly",
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "ec2:Get*"
      ],
      "Resource": "*"
    }
  ]
}

Permission Configuration Guide

Use Case Recommended Configuration Notes
Production Operations AdministratorAccess Full AWS management capabilities
Development/Testing Service-specific policies Limit to required services (EC2, S3, etc.)
Read-Only Auditing ReadOnlyAccess View resources without modification
Specific Tasks Custom minimal policy Grant only necessary permissions

Security Best Practices

  1. Principle of Least Privilege - Grant only the minimum permissions required for users' actual tasks
  2. Regular Audits - Review IAM Role permissions periodically to ensure they remain appropriate
  3. CloudTrail Monitoring - Enable CloudTrail to track all API calls made through Kiro-CLI
  4. Environment Separation - Use different IAM Roles for production, staging, and development environments
  5. Temporary Elevation - For high-risk operations (e.g., resource deletion), consider implementing approval workflows

Note: If you do not need IAM sync, Secrets Manager, or SNS features, those permissions are optional. Users can still log in via SSO and be created automatically on first login. However, Kiro-CLI operational permissions are essential for users to perform any AWS operations through the terminal.

Steps to Attach the Role

  1. AWS Console → IAM → Roles → Create role
  2. Trusted entity: AWS service → EC2
  3. Attach policies:
    • Create inline policy for platform base permissions (IAM Identity Center, Secrets Manager, SNS)
    • Attach AWS managed policy for Kiro-CLI operations (e.g., AdministratorAccess or service-specific policies)
    • Name the role KiroCLIPlatformRole
  4. EC2 Console → select your instance → Actions → Security → Modify IAM role → attach the role

For detailed configuration examples, see EC2_DEPLOYMENT_V1.1.md

Quick Start

🚀 New in v1.1: Automated deployment in 3 simple steps!

Prerequisites: Make sure you have installed Kiro CLI before proceeding.

# 1. Connect to EC2
ssh -i /path/to/your-key.pem ubuntu@<YOUR_EC2_IP>

# 2. Download code to ~/kirocli-platform
git clone https://github.com/YOUR_USERNAME/vue-kirocli-platform.git ~/kirocli-platform
cd ~/kirocli-platform

# 3. Run installation script
chmod +x scripts/install.sh
./scripts/install.sh

That's it! The script will guide you through the rest.

What the script does:

  • ✅ Installs all system dependencies (Node.js, Python, Nginx, SQLite)
  • ✅ Installs Gotty terminal tool
  • ✅ Generates TLS certificates
  • ✅ Configures backend environment and database
  • ✅ Builds frontend application
  • ✅ Configures Nginx and systemd services
  • ✅ Starts all services

Installation time: ~10-15 minutes

For detailed manual deployment steps, see EC2_DEPLOYMENT_V1.1.md.

Post-Installation Configuration

After the installation script completes:

1. Configure AWS Secrets Manager (Required)

The installation script will guide you through Secrets Manager configuration. If you skipped it, follow these steps:

  1. Create a secret in AWS Secrets Manager:

    • Secret name: kirocli-platform/production (or the name you specified)
    • Secret type: Other type of secret
    • Secret value (JSON format):
    {
  "SECRET_KEY": "<random-generated-key>",
  "SAML_IDP_X509_CERT": "<certificate-from-iam-identity-center>"
}

  2. Ensure EC2 IAM Role has permissions:

    • secretsmanager:GetSecretValue
    • secretsmanager:DescribeSecret

  3. Restart the backend service:

    sudo systemctl restart kirocli-backend

2. Verify Deployment

Open http://<EC2_PUBLIC_IP>:3000 in your browser and click "SSO Login".

If you encounter issues, see the Troubleshooting section or IAM Identity Center Configuration Guide.

Updating the Application

From v1.0 to v1.1

See CHANGELOG.md for detailed migration instructions.

Quick steps:

cd ~/kirocli-platform
git pull origin main

# Run database migration
cd backend
source .venv/bin/activate
python scripts/upgrade_db.py

# Update Nginx configuration
sudo cp nginx/kirocli_map.conf /etc/nginx/conf.d/
sudo cp nginx/kirocli /etc/nginx/sites-available/
sudo touch /etc/nginx/conf.d/gotty_routes.conf
sudo chown $USER:$USER /etc/nginx/conf.d/gotty_routes.conf
sudo nginx -t && sudo systemctl reload nginx

# Rebuild frontend
cd ../frontend
npm install && npm run build

# Restart backend
sudo systemctl restart kirocli-backend

Within v1.1 (patch updates)

cd ~/kirocli-platform
git pull origin main
sudo systemctl restart kirocli-backend
cd frontend && npm install && npm run build

Troubleshooting

Common Deployment Issues

SAML login fails with invalid_response error

Cause: SAML_IDP_X509_CERT certificate not configured in AWS Secrets Manager.

Solution:

# 1. Get certificate from IAM Identity Center console
# 2. Create or update secret with certificate
aws secretsmanager update-secret \
  --secret-id kirocli-platform/production \
  --region cn-northwest-1 \
  --secret-string '{
    "SECRET_KEY": "your-secret-key",
    "SAML_IDP_X509_CERT": "-----BEGIN CERTIFICATE-----\nYOUR_CERT_HERE\n-----END CERTIFICATE-----"
  }'

# 3. Restart backend
sudo systemctl restart kirocli-backend

Verify:

  • Certificate includes -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
  • EC2 IAM Role has secretsmanager:GetSecretValue permission
  • Secret name matches SECRETS_MANAGER_SECRET_NAME in .env

Terminal shows "connection close" or black screen

Cause: KIRO_CLI_PATH not configured in .env file.

Solution:

# Fix KIRO_CLI_PATH
which kiro-cli
sed -i "s|KIRO_CLI_PATH=.*|KIRO_CLI_PATH=$(which kiro-cli)|" \
  ~/kirocli-platform/backend/.env
sudo systemctl restart kirocli-backend

Other causes:

  • Kiro CLI not authenticated (run kiro-cli manually to complete login first)
  • Nginx configuration error (check sudo nginx -t)
  • Gotty routes not configured (check /etc/nginx/conf.d/gotty_routes.conf)

SAML "No access" error after login

Cause: Subject attribute mapping incorrect in IAM Identity Center.

Solution:

  • In IAM Identity Center console, go to your SAML application
  • Check Attribute mappings tab
  • Ensure Subject is mapped to ${user:email} with format emailAddress
  • Do NOT use ${user:name}

Backend fails to start

Check logs:

sudo journalctl -u kirocli-backend -n 50 --no-pager

Common causes:

  • Secrets Manager secret not found → Create secret with required fields
  • Database locked → Stop backend, remove lock file, restart
  • Port 8000 already in use → Kill conflicting process

Frontend build fails (OOM)

Solution:

# Add swap space
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Retry build
cd ~/kirocli-platform/frontend
npm run build

Nginx 500 error

Solution:

# Fix permissions
chmod 755 $HOME
chmod -R 755 ~/kirocli-platform/frontend/dist

# Restart Nginx
sudo systemctl restart nginx

Verification Commands

# Check all services status
sudo systemctl status kirocli-backend
sudo systemctl status nginx

# Check backend health
curl http://127.0.0.1:8000/api/v1/health

# Check backend logs
sudo journalctl -u kirocli-backend -f

# Check Nginx logs
sudo tail -f /var/log/nginx/error.log

# Verify KIRO_CLI_PATH
grep "KIRO_CLI_PATH" ~/kirocli-platform/backend/.env

# Check Gotty processes
ps aux | grep gotty

Monthly Cost Estimate

Running Costs (China Ningxia Region)

Team Size Configuration Monthly Cost Per User
10-20 users t3.medium + 20GB ¥329/month ¥16.45/month
50-100 users t3.large + 50GB ¥683/month ¥13.66/month
100+ users t3.xlarge + 100GB + ALB ¥1,385/month ¥13.85/month

Cost Breakdown (Small Team Example)

Item Specification Monthly Cost
EC2 Instance t3.medium (2 vCPU, 4GB RAM) ¥306.60
EBS Storage gp3 20GB ¥16.00
Data Transfer 10GB outbound ¥6.00
IAM Identity Center Free ¥0
Secrets Manager 1 secret ¥0.40
Total ¥329/month

Cost Optimization Tips

💡 Reserved Instances: Save 30-50% on EC2 costs

💡 Schedule Start/Stop: Save 60% by running only during business hours

💡 Spot Instances: Save 70% for dev/test environments

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT-0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages

Generated from amazon-archives/__template_MIT-0