Axiomly Complete User Guide

What is Axiomly?

Axiomly is an AI governance platform that helps organizations control which libraries, packages, tools, and configurations AI agents can use. It acts as a centralized approval registry that ensures security, compliance, and consistency across your development teams.

Key Benefits

• Security: Only approved, vetted libraries can be used
• Compliance: Automatic tracking and auditing of all dependencies
• Consistency: Everyone uses the same approved tools and versions
• Control: Centralized management of all development dependencies
• Transparency: Clear approval workflow with audit trails

Getting Started

Step 1: Access the Web Portal

Navigate to your organization's Axiomly URL (ask your administrator for the exact URL).

Step 2: Sign In

Option A: Single Sign-On (SSO)

• Click "Sign in with Microsoft" (or your organization's SSO provider)
• Authenticate with your organizational account

Option B: Local Authentication

• Enter your username and password
• Click "Sign In"

Step 3: First-Time Setup

After logging in for the first time:

1. Your API key is automatically generated
2. Review your profile information
3. Download your personalized installer
4. Install IDE integration

Web Portal Guide

Homepage (User Dashboard)

The homepage shows all approved items with powerful search and filtering:

• Search Bar: Find specific items by name with real-time results
• Filters: Filter by type (Library, MCP Server, Extension, etc.) and status
• Sort Options: Sort by name, type, date added, or popularity
• Download Installer Button: Get your personalized IDE installer
• Item Cards: Click any item to view detailed information

Item Details Page

View comprehensive information about any approved item:

• Basic Information: Name, version, type, status, description
• Security Assessment: Axiomly risk analysis, vulnerability scan, health metrics
• API Access: Code snippets for using the item via API
• Metadata: Date added, last updated, approval history

Profile Page

View and manage your account:

• User information (name, email, role)
• API key status and prefix
• Last used timestamp
• Actions: Regenerate API key, Download installer

Request Access Page

Submit approval requests for new items:

1. Select item type (Library, MCP Server, Extension, etc.)
2. Enter name and version
3. Provide justification (be specific!)
4. Submit request

Security Assessment

What is Security Assessment?

Axiomly provides automated security analysis for library packages by aggregating data from trusted security research firms, package health services, and official package repositories.

Axiomly Score

The Axiomly Score is a comprehensive risk assessment (0-100, higher is better):

• 90-100: Excellent - Low risk, well-maintained, secure
• 70-89: Good - Acceptable risk, actively maintained
• 50-69: Fair - Moderate risk, review carefully
• Below 50: Poor - High risk, consider alternatives

Viewing Security Assessments

From Item Details Page

1. Click any library item from the homepage
2. Scroll to "Security Assessment" card
3. Click "View Full Assessment" for detailed analysis

From Edit Item Page (Admins)

1. Go to Tenant Admin > Approved Items
2. Click "Edit" on any library
3. Security assessment loads automatically in right panel
4. Change version to see assessment for different versions

From Approval Requests (Admins)

Quick ratings appear inline for each library request showing:

• 📊 Axiomly Score (color-coded: green/yellow/red)
• 🛡️ Vulnerability Count
• 💊 Health Score

Using Security Assessments

For Users

• Check security assessment before requesting approval
• Look for high Axiomly Scores (70+)
• Avoid packages with critical vulnerabilities
• Consider alternatives if score is low

For Administrators

• Review security assessment when approving requests
• Use quick ratings to prioritize review queue
• Reject packages with critical vulnerabilities
• Require justification for low-scoring packages
• Periodically review approved items for new vulnerabilities

AI-Powered Risk Analysis

Automatic Package Scanning

When an approval request is submitted, Axiomly automatically downloads and analyzes the package source code using AI. The analysis checks for:

• Obfuscated Code — Base64, hex encoding, eval/exec with encoded strings
• Install Hooks — postinstall/preinstall scripts running arbitrary code
• Network Calls — Hardcoded IPs, suspicious domains, data exfiltration
• File System Access — Reading ~/.ssh, ~/.aws, env files, writing to disk
• Process Spawning — Shell commands, child process execution
• Credential Harvesting — Environment variables, tokens, API keys
• Binary Blobs — Encoded data or binaries embedded in source
• Prototype Pollution — Object prototype manipulation patterns
• Backdoor Patterns — Conditional execution based on hostname/IP/env
• Known Incident Dependencies — Dependencies involved in known security incidents
• Typosquatting — Dependencies with names similar to popular packages
• Dependency Confusion — Internal-looking package names on public registries
• Pinned Compromised Versions — Dependencies pinned to known-bad versions
• License Risk — Copyleft or restrictive licensing

Supply Chain Version Diff Analysis

When a newer version of an already-approved package is requested, Axiomly performs a version diff analysis — comparing the old and new versions to detect suspicious changes between releases, such as newly added network calls, obfuscated code, or dependency changes.

Supported Ecosystems

Risk analysis supports packages from: npm, PyPI, NuGet, RubyGems, Maven, Cargo, Go, and Packagist.

Viewing Risk Analysis Results

1. Go to Tenant Admin → Approval Requests
2. Click "View Details" on any analyzed request
3. The Risk Analysis panel shows the verdict, confidence score, and detailed findings for each check

Verdicts

• Benign — No suspicious patterns detected. Safe to approve.
• Suspicious — Potential risk indicators found. Manual review recommended.
• Malicious — Strong indicators of malicious intent. Do not approve.
• Not Applicable — Package is too large for source code diff analysis (common for packages that bundle binaries like browser engines or native modules). Rely on the AI Security Assessment for risk evaluation.
• Error — Analysis could not complete. Retry or review manually.

IDE Integration

Supported IDEs

Axiomly provides native integration for multiple AI-powered IDEs across Windows, macOS, and Linux:

• Kiro IDE - MCP server integration with steering documents and hooks (Windows, macOS, Linux)
• Kiro CLI - MCP server integration for command-line AI workflows (Windows, macOS, Linux)
• Claude - MCP server integration with steering documents (Windows, macOS, Linux)
• JetBrains IDEs - IntelliJ IDEA, PyCharm, WebStorm, Rider, and more (Windows, macOS, Linux)
• VS Code - Full extension with status bar, governance panel, and MCP server for Copilot (Windows, macOS, Linux)
• Cursor IDE - MCP server integration with steering documents and hooks (Windows, macOS, Linux)

Installation Process

Step 1: Download Installer

1. Log in to Axiomly web portal
2. Click "Download Installer" button
3. Select your IDE
4. Save the PowerShell script

Step 2: Run Installer

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File .\axiomly-[ide]-installer.ps1

macOS/Linux (Bash):

chmod +x axiomly-[ide]-installer.sh
./axiomly-[ide]-installer.sh

The installer will:

• ✅ Install VS Code extension (or configure MCP server for Cursor/Kiro)
• ✅ Deploy package manager wrappers to C:\ProgramData\axinstall
• ✅ Set environment variables (AXIOMLY_API_KEY, AXIOMLY_BASE_URL)
• ✅ Update PowerShell profile with wrapper functions
• ✅ Configure steering documents and governance rules

Step 3: Restart IDE

Close and reopen your IDE for changes to take effect.

Step 4: Verify Installation

• Kiro IDE: Open MCP Servers panel, look for "axiomly-governance"
• Kiro CLI: Run kiro mcp list to verify "axiomly-governance" is listed
• Claude: Settings → Developer → MCP Servers, look for "axiomly-governance"
• JetBrains IDEs: AI Assistant settings, check MCP server configuration
• VS Code: Check Extensions panel for "Axiomly Governance"
• Cursor IDE: Open MCP Servers panel, look for "axiomly-governance"

How IDE Integration Works

Axiomly provides multi-layered governance enforcement:

Layer 1: AI Agent Governance (MCP Server)

• ✅ AI agent checks Axiomly before suggesting packages
• ✅ Validates dependencies when opening projects
• ✅ Offers to submit approval requests
• ✅ Provides security assessment data

Layer 2: Command-Line Protection

• ✅ Enforces governance for direct package installations
• ✅ Validates against Axiomly before executing
• ✅ Blocks unapproved packages at installation time
• ✅ Works even if AI agent is bypassed

Layer 3: Steering Documents

• ✅ Instructs AI agents on governance policies
• ✅ Automatically loaded in every conversation
• ✅ Ensures consistent behavior across all AI agents

Command-Line Protection

What is Command-Line Protection?

Axiomly enforces governance even when packages are installed directly from the command line, providing an additional security layer beyond AI agent checks.

Supported Package Managers

• Python - pip package installer
• Node.js - npm package manager
• VS Code - Extension installer
• Claude - CLI commands

User Experience

When Package is Approved

PS> pip install flask

Checking Axiomly approval...
✓ Approved - Installing flask...

When Package is Blocked

PS> pip install unapproved-package

Checking Axiomly approval...
✗ Blocked - Package not approved

Would you like to request approval? (Y/N):

Troubleshooting

Protection Not Working

Symptoms: Packages install without Axiomly check

Solutions:

1. Re-download installer from Axiomly profile
2. Run installer to update configuration
3. Restart your terminal/IDE
4. Test with a known approved package

API Keys & Authentication

What is an API Key?

An API key is a unique identifier that:

• Authenticates your IDE with Axiomly
• Links your actions to your user account
• Enables audit logging
• Controls rate limiting

API Key Format

axiomly_xK8vN2mP9qR4sT6uV8wX0yZ1aB3cD5eF7gH9iJ1kL3mN5oP7qR9sT1uV3wX5yZ7

Viewing Your API Key

1. Log in to Axiomly web portal
2. Go to Profile page
3. View API Key Status section
4. See key prefix (first 8 characters)

API Key Security Best Practices

Approval Workflow

Requesting Approval

Method 1: Through IDE (Recommended)

When AI agent encounters an unapproved item, it will offer to submit a request on your behalf.

Method 2: Through Web Portal

1. Go to Request Access page
2. Fill out the form
3. Provide detailed justification
4. Submit request

Justification Tips

Request Statuses

• PENDING: Awaiting review by administrators
• APPROVED: Request approved, item now available
• REJECTED: Request denied (see rejection reason)
• NEEDS_INFO: Administrators need more information

Groups

For users with TenantAdmin role

Groups let you control which steering documents apply to which users. This is useful when different teams need different governance policies or coding standards.

How Groups Work

Creating a Group

1. Go to Tenant Admin > Groups
2. Click "Create Group"
3. Enter a name (e.g., "Backend Team", "Security Team")
4. Optionally add a description
5. Click "Create Group"

Managing Group Members

1. Go to Tenant Admin > Groups
2. Click "Edit" on the group
3. In the Users section, select a user from the dropdown and click "Add"
4. To remove a user, click the remove button next to their name

Assigning Steering Documents to Groups

There are two ways to assign steering documents to groups:

Method 1: From the Group Edit Page

1. Go to Tenant Admin > Groups > Edit
2. In the Steering Documents section, select a document from the dropdown and click "Add"
3. To remove a document, click the remove button next to it

Method 2: From the Item Create/Edit Page

1. When creating or editing a Steering Document item, a "Assign to Groups" section appears
2. Check the groups that should receive this document
3. Leave all unchecked to make the document global (visible to everyone)

Example Scenarios

• Global governance policy: Create a steering document and don't assign it to any group. All users see it.
• Team-specific standards: Create a "Python Standards" steering document and assign it to the "Backend Team" group. Only backend team members see it.
• Mixed approach: Have a global security policy (no group) plus team-specific coding standards (assigned to respective groups).

Administration

For users with TenantAdmin or Approver roles

Tenant Admin Dashboard

Overview of your tenant with statistics, recent activity, and quick actions.

Managing Users

• View all users in your tenant
• Add new users (SSO or local authentication)
• Edit user details and roles
• Disable users when they leave

User Roles

• ReadOnly: View approved items only
• Builder: View items + submit approval requests
• Approver: Builder + approve/reject requests
• TenantAdmin: Full administrative access

Managing Approved Items

• Browse all approved items
• Add new approved items
• Edit existing items
• Deprecate or disable items

Managing Approval Requests

1. View all approval requests
2. Review request details and justification
3. Research the item (documentation, security advisories)
4. Approve, reject, or request more information

Auto-Approval

Tenant admins can configure automatic approval for packages that meet minimum security thresholds. When enabled, approval requests are instantly approved if all three scores meet your organization's requirements — no manual review needed.

How It Works

1. A developer submits an approval request (via IDE or CLI)
2. Axiomly evaluates the package against three scores:
   • Axiomly Score — Vulnerabilities, health, and maintenance (0-100)
   • AI Security Assessment — Security, quality, popularity, and maintenance (0-100)
   • Supply Chain Analysis — Code diff analysis confidence with Benign verdict required (0-100)
3. If all scores meet or exceed the configured thresholds, the request is approved automatically
4. If any score falls below the threshold, the request stays pending for manual admin review

Safety Guardrails

• Packages with critical vulnerabilities are never auto-approved, regardless of scores
• Supply chain analysis must return a Benign verdict (Suspicious or Malicious are always blocked)
• Only Library type items are eligible for auto-approval (MCP servers, extensions, etc. require manual review)
• Auto-approval can optionally require supply chain analysis to complete before approving

Configuring Auto-Approval

1. Go to Tenant Admin → Approval Requests
2. Click the 🤖 Auto-Approval collapsible panel
3. Toggle Enable auto-approval on
4. Set minimum thresholds for each score (default: 70/100)
5. Optionally require supply chain analysis to complete before auto-approving
6. Click Save

Other Admin Features

• Groups: Create groups to assign specific steering documents to specific users (see Groups section)
• API Keys: View and revoke user API keys
• SSO Configuration: Set up Single Sign-On
• Subscription Management: View plan and billing
• Audit Logs: Track all activities
• Uninstallers: Download removal scripts for all supported IDEs (Kiro IDE, Kiro CLI, Claude, JetBrains, VS Code, Cursor) across all platforms (Windows, macOS, Linux) - Tenant Admins only

Troubleshooting

Common Issues

Getting Help

For technical issues: support@axiomly.com

For billing questions: billing@axiomly.com

For security concerns: security@axiomly.com

Best Practices

For Users

For Administrators