Terra Security Commands
Overview
Terra Security is an agentic offensive security platform that combines human pentesters with AI agents to streamline penetration testing and vulnerability assessment. The platform launched Terra Portal in March 2026 and raised $30M Series A funding from Felicis, establishing itself as a leader in AI-driven security testing.
Key Features
- Ambient AI Agents: Autonomous reconnaissance, vulnerability scanning, and exploitation validation
- Copilot AI Agents: Human-directed controlled exploitation with real-time guidance
- Human-in-the-Loop Governance: Security controls ensure responsible testing within defined scope
- Automated Reporting: Comprehensive vulnerability documentation with remediation guidance
- Enterprise Integration: CI/CD pipelines, ticketing systems, SIEM platforms
Platform Architecture
Terra Portal (Desktop/Web App)
├── Agent Management Console
├── Scope & Workflow Configuration
├── Real-time Monitoring Dashboard
├── Vulnerability Reporting Engine
└── Integration Hub
Terra Portal Setup
Installation
Desktop Application
| Step | Action |
|---|---|
| 1 | Download Terra Portal from terra.security |
| 2 | Run installer (Windows/macOS/Linux) |
| 3 | Accept security permissions for system-level network access |
| 4 | Launch and authenticate with organizational credentials |
| 5 | Configure proxy settings if required |
Web-Based Console
Access via: https://portal.terra.security
Authentication: SSO/OAuth or API token
Requirements: Modern browser (Chrome, Firefox, Safari, Edge)
Initial Configuration
| Setting | Description |
|---|---|
| Organization Setup | Create/join organization, configure admin permissions |
| API Credentials | Generate authentication tokens for CI/CD and API access |
| Network Configuration | Define internal networks, proxy settings, VPN requirements |
| Notification Preferences | Email, Slack, webhook alerts for agent activity and findings |
| Default Agent Settings | Base configuration for Ambient and Copilot agent instances |
| Compliance Framework | Select applicable standards (OWASP, PTES, NIST) |
Authentication Methods
# API Token Authentication
Authorization: Bearer YOUR_API_TOKEN
X-Organization-ID: org_xxxxx
# SSO Integration
Provider: Okta, Azure AD, Google Workspace
Auto-provisioning: Enabled/Disabled
# Service Accounts
For CI/CD: Create service account with scoped permissions
Token rotation: 90-day default interval
Agent Types
Ambient AI Agents
Autonomous agents operating within defined scope and depth parameters to continuously assess security posture.
| Agent Type | Capabilities |
|---|---|
| Asset Discovery Agent | Network reconnaissance, inventory cataloging, service identification |
| Code Review Agent | Static analysis, dependency scanning, secret detection |
| Test Case Generation Agent | Automatic test scenario creation based on discovered assets |
| Reachability Analysis Agent | Network path mapping, firewall rule analysis, access control validation |
| Autonomous Pentesting Agent | Vulnerability scanning, exploitation attempts, impact validation |
| Documentation Agent | Evidence gathering, finding validation, report generation |
| Remediation Agent | Configuration recommendations, patch guidance, control suggestions |
Configuration Example
Ambient Agent Configuration:
Asset Discovery:
enabled: true
scan_frequency: daily
scope: internal_networks_only
include_cloud: true
Code Review:
enabled: true
repositories: auto_discover
scan_pull_requests: true
secret_detection: strict
Autonomous Pentesting:
enabled: true
depth_level: 3
max_impact: "informational"
revert_changes: true
human_approval_threshold: critical
Copilot AI Agents
Human-directed agents providing real-time assistance during controlled exploitation and manual testing.
| Copilot Function | Use Case |
|---|---|
| Exploitation Guidance | Step-by-step assistance for manual exploitation workflows |
| Vulnerability Interpretation | Explain findings, impact assessment, exploitation prerequisites |
| Remediation Planning | Generate fix strategies, patch recommendations, workaround options |
| Evidence Documentation | Automated screenshot/log capture, finding validation |
| Reporting Assistance | Real-time report generation, executive summary creation |
Copilot Interaction Workflow
1. Pentester identifies vulnerability
↓
2. Invoke Copilot: "/assist vuln_id"
↓
3. Copilot analyzes context:
- Vulnerability details
- System configuration
- Historical data
↓
4. Provides recommendations:
- Exploitation steps
- Required tools/payloads
- Risk assessment
↓
5. Pentester executes with guidance
↓
6. Copilot documents findings automatically
Workflow Configuration
Scope Definition
Define the boundaries and targets for agent activity.
| Configuration | Options |
|---|---|
| Asset Scope | IP ranges, hostnames, domains, cloud accounts, APIs |
| Technology Scope | Web apps, APIs, infrastructure, cloud services, mobile |
| Exclusions | Production databases, customer PII, third-party systems |
| Environment Tagging | Dev, Staging, Production, Internal, External |
| Regulatory Scope | PCI-DSS, HIPAA, SOC2, GDPR compliance requirements |
Depth & Intensity Controls
| Control | Purpose | Levels |
|---|---|---|
| Reconnaissance Depth | How thoroughly agents discover assets | 1-5 (1=shallow, 5=exhaustive) |
| Exploitation Depth | How deeply agents attempt to exploit vulnerabilities | 1-5 (1=detection only, 5=full compromise) |
| Intensity/Rate | Query load and test frequency | Low, Medium, High, Custom |
| Time Windows | When agents operate | Always, Business hours, Custom schedule |
| Concurrent Agents | Maximum simultaneous agent instances | 1-50+ per agent type |
Impact Controls
Governance mechanisms to ensure responsible testing.
| Control | Configuration |
|---|---|
| Auto-Revert Changes | Automatically rollback modifications (enabled by default) |
| Impact Threshold | Maximum allowed disruption (info, low, medium, high) |
| Human Approval Gate | Require approval for critical-impact actions |
| Automatic Escalation | Alert administrators if impact exceeds threshold |
| Resource Limits | CPU/memory/bandwidth caps for agent activity |
| Rollback Window | Time to manually revert before automatic rollback |
Workflow Templates
Workflow: Continuous Assessment
Schedule: Daily (02:00 UTC)
Agents:
- ambient.asset_discovery (depth: 3)
- ambient.code_review (depth: 4)
- ambient.vulnerability_scanning (depth: 2)
Scope: internal_networks
Impact: low
Approval: automated
Workflow: Quarterly Pentest
Schedule: Quarterly
Agents:
- ambient.asset_discovery (depth: 5)
- ambient.autonomous_pentesting (depth: 4)
- copilot.exploitation (depth: 4)
Scope: all_production_systems
Impact: medium
Approval: human_required
Duration: 2 weeks
Workflow: Incident Response
Trigger: manual
Agents:
- ambient.reachability_analysis
- ambient.autonomous_pentesting (depth: 4)
- copilot.exploitation
Scope: affected_systems
Impact: high (with approval)
Approval: human_required
Reconnaissance Features
Automated Asset Discovery
AI agents automatically catalog organizational assets and attack surfaces.
| Discovery Method | Coverage |
|---|---|
| Network Scanning | CIDR range analysis, service enumeration, OS fingerprinting |
| DNS Enumeration | Subdomain discovery, DNS record analysis, zone transfers |
| Cloud API Enumeration | AWS, Azure, GCP account discovery and service mapping |
| Web Crawling | JavaScript rendering, hidden endpoint discovery, form identification |
| Certificate Transparency | Historical domain discovery, SSL/TLS certificate tracking |
| WHOIS/ASN Analysis | IP ownership, autonomous system mapping, geographic analysis |
| Port Scanning | TCP/UDP ports, service identification, version detection |
Attack Surface Mapping
Discovery Output Hierarchy:
Organization
├── Networks
│ ├── Internal Networks
│ │ ├── Subnets
│ │ │ ├── Hosts
│ │ │ │ ├── Services (HTTP, SSH, DB, etc.)
│ │ │ │ │ ├── Endpoints
│ │ │ │ │ └── Technologies
│ │ │ │ └── Vulnerabilities
│ │ │ └── Relationships
│ │ └── Firewall Rules
│ └── External Networks
├── Cloud Resources
│ ├── AWS Accounts
│ ├── Azure Subscriptions
│ ├── GCP Projects
│ └── Cloud Storage
├── Web Applications
│ ├── Endpoints
│ ├── Authentication Methods
│ ├── APIs
│ └── Third-party Integrations
├── Code Repositories
│ ├── Internal repos
│ ├── Public exposure
│ └── Dependency inventory
└── Third-party Integrations
├── SaaS applications
├── API connections
└── Data flows
Asset Inventory Management
| Feature | Description |
|---|---|
| Automatic Tagging | AI categorizes assets by type, criticality, exposure level |
| Relationship Mapping | Connects assets showing data flows and dependencies |
| Change Tracking | Detects new assets, removed assets, configuration changes |
| Risk Scoring | Assigns risk based on exposure, vulnerabilities, criticality |
| Historic Tracking | Maintains discovery history for trend analysis |
| Export Capabilities | CSV, JSON, XLSX formats for external tools |
Vulnerability Assessment
AI-Driven Scanning
Intelligent vulnerability identification combining multiple detection methods.
| Scan Type | Description |
|---|---|
| Pattern-Based Scanning | Known vulnerability signatures (CVSS, CWE databases) |
| Behavioral Analysis | Anomalous configuration detection, security control gaps |
| Dependency Scanning | Library/package vulnerability detection with supply chain analysis |
| Secret Detection | API keys, credentials, tokens in code and configuration |
| Configuration Audit | Security best practice compliance validation |
| Access Control Review | Excessive permissions, unused access, segregation violations |
| Cryptography Analysis | Weak algorithms, certificate validation issues, encryption gaps |
Vulnerability Prioritization
AI agents automatically prioritize findings based on:
Priority Score = (CVSS × Exploitability) × Accessibility × Business Impact
Factors:
- CVSS 3.1 Base Score
- Exploitability:
* Requires network access
* Requires user interaction
* Requires authentication
* Attack complexity
- Accessibility:
* External exposure
* Internal accessibility
* Direct/indirect access
- Business Impact:
* PII exposure
* System criticality
* Revenue impact
* Compliance violation
Output: Critical → High → Medium → Low → Informational
Vulnerability Categorization
| Category | Examples |
|---|---|
| Authentication | Default credentials, weak authentication, session management flaws |
| Authorization | Privilege escalation, insecure direct object references, broken access control |
| Injection Flaws | SQL injection, command injection, LDAP injection, template injection |
| Sensitive Data Exposure | Unencrypted data, inadequate encryption, data leakage, PII exposure |
| XML/External Entities | XXE attacks, billion laughs, external entity injection |
| Broken Access Control | Insecure direct object references, missing access control, path traversal |
| Security Misconfiguration | Default configuration, unnecessary services, verbose error messages |
| Insecure Deserialization | Object injection, gadget chains, deserialization attacks |
| Using Components with Known Vulnerabilities | Outdated libraries, unpatched dependencies |
| Insufficient Logging | Missing audit trails, inadequate monitoring, poor alerting |
Exploitation Workflows
Human-Governed Exploitation
All exploitation activities maintain human oversight and control.
Exploitation Workflow
1. Discovery Phase
- Agents identify vulnerability
- Assess exploitability
- Determine prerequisites
↓
2. Planning Phase
- Generate exploitation strategy
- Estimate impact
- Identify revert steps
↓
3. Approval Gate
- If critical impact: requires human approval
- If medium impact: automated approval with notification
- If low impact: automated approval
↓
4. Execution Phase
- Execute exploitation steps
- Monitor for unexpected behavior
- Capture evidence
↓
5. Validation Phase
- Confirm successful exploitation
- Document impact
- Identify lateral movement opportunities
↓
6. Revert Phase
- Execute pre-planned revert steps
- Verify system restoration
- Clean up artifacts
↓
7. Documentation Phase
- Generate findings report
- Document proof-of-concept
- Create remediation recommendations
Safety Controls During Exploitation
| Control | Function |
|---|---|
| Pre-execution Validation | Verify target is in scope before any action |
| Dry-run Mode | Execute exploitation logic without actual impact |
| Rollback Planning | Pre-plan and validate revert steps before execution |
| Real-time Monitoring | Watch system health during exploitation |
| Automatic Halt | Stop if unexpected conditions detected |
| Resource Throttling | Limit CPU/network/memory consumption |
| Time Limits | Automatic termination after duration threshold |
| Change Logging | Audit trail of all modifications |
| Isolation Mode | Optional: isolate target during testing |
Exploitation Capabilities
| Type | Description |
|---|---|
| Credential Testing | Default credential attempts, brute force with controls |
| Known Vulnerability Exploitation | CVE-based exploits with proven success paths |
| Logic Flow Exploitation | Business logic flaws, workflow manipulation |
| Lateral Movement | Post-compromise movement with scope controls |
| Privilege Escalation | Local/OS-level escalation with permission validation |
| Data Exfiltration Validation | Simulated data access with no actual extraction |
| Persistence Mechanism Testing | Backdoor placement validation with automatic removal |
Reporting
Automated Vulnerability Reports
Terra Security generates comprehensive reports automatically throughout testing.
Report Components
| Section | Contents |
|---|---|
| Executive Summary | Key findings, risk overview, remediation timeline |
| Vulnerability Details | Finding ID, title, severity, CVSS, description, evidence |
| Proof of Concept | Step-by-step exploitation walkthrough, screenshots, logs |
| Impact Assessment | Business impact, data exposure, system compromise scope |
| Remediation Guidance | Prioritized fix recommendations, patch guidance, workarounds |
| Compliance Mapping | Link findings to standards (OWASP, PTES, NIST, PCI-DSS) |
| Timeline & Metrics | Testing duration, coverage statistics, scope details |
| Management Summary | Risk timeline, vulnerability trend, metrics dashboard |
Report Customization
Report Template Configuration:
Output Formats:
- PDF: Executive, detailed, or technical variants
- HTML: Interactive, shareable version
- JSON: API integration, ticketing automation
- CSV: Bulk import to tools
Customization Options:
branding: organization_logo
sections:
- include_evidence: true
- include_timeline: true
- include_remediation: true
- include_compliance: true
recipients:
- ciso@company.com
- security-team@company.com
schedule:
- daily: summary_report
- weekly: comprehensive_report
- on_critical: immediate_alert
Finding Lifecycle Management
| Status | Description |
|---|---|
| Open | New finding, not yet addressed |
| Acknowledged | Organization confirmed receipt and assessed |
| In Progress | Remediation effort underway |
| Resolved | Fix applied and validated |
| False Positive | Finding determined to be invalid, documented reasoning |
| Risk Accepted | Business decision to accept risk, signed off |
| Deferred | Accepted but not prioritized for current timeline |
Integration
CI/CD Pipeline Integration
Embed Terra Security testing into development workflows.
# GitLab CI Example
security_scan:
stage: test
script:
- terra-cli scan \
--workflow continuous \
--scope repository \
--report-format json \
--output artifacts/terra-report.json
artifacts:
reports:
sast: artifacts/terra-report.json
paths:
- artifacts/terra-report.json
expire_in: 30 days
# GitHub Actions Example
name: Terra Security Scan
on: [pull_request, push]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Terra Security Scan
env:
TERRA_API_KEY: ${{ secrets.TERRA_API_KEY }}
run: |
terra-cli scan \
--scope ./src \
--depth 3 \
--fail-on critical
Ticketing System Integration
Automatically create and manage security findings in issue trackers.
| Integration | Features |
|---|---|
| Jira | Auto-create issues, assign to teams, set priority, link to epics |
| Azure DevOps | Create work items, integrate with backlogs, track remediation |
| GitHub Issues | Create issues, link to PRs, track resolution |
| Linear | Create issues with custom fields, link to projects |
| ServiceNow | Create incidents/change requests, incident management workflow |
| Slack | Real-time notifications, finding summaries, remediation tracking |
SIEM & Monitoring Integration
| Platform | Integration Type |
|---|---|
| Splunk | Ingest finding logs, create searches, alerts, dashboards |
| ELK Stack | Feed to Elasticsearch for analysis and visualization |
| Datadog | Metrics export, APM correlation, alerting |
| New Relic | Application security data, vulnerability tracking |
| Prometheus | Metrics export for security dashboards |
| CloudWatch | AWS integration, log streaming, metric publishing |
Safety Controls
Scope Enforcement
Prevent testing outside authorized boundaries.
Scope Enforcement:
Network Scope:
allowed_ranges:
- 10.0.0.0/8
- 192.168.1.0/24
blocked_ranges:
- 0.0.0.0/0
enforcement: strict
Asset Scope:
allowed_assets:
- tag: testing_approved
- tag: staging_only
blocked_assets:
- tag: production
- tag: customer_data
- hostname: "*prod*"
enforcement: strict
Application Scope:
allowed_apps:
- internal_web_apps
- staging_environments
blocked_apps:
- production_databases
- customer_data_stores
enforcement: strict
Depth Limiting
Control how deeply agents operate.
| Depth Level | Reconnaissance | Exploitation | Scope |
|---|---|---|---|
| 1 - Light | Basic discovery, no intrusive scanning | Detection only | Pre-approved assets |
| 2 - Standard | Active scanning, vulnerability identification | Safe exploitation attempts | Standard testing scope |
| 3 - Moderate | Detailed enumeration, configuration review | Limited lateral movement | Extended scope with approval |
| 4 - Advanced | Comprehensive mapping, dependency analysis | Advanced exploitation, limited persistence testing | Full scope with oversight |
| 5 - Exhaustive | Complete reconnaissance, all available techniques | Full exploitation, post-compromise activities | Maximum scope with human approval |
Impact Controls
Prevent unintended damage.
Impact Control Thresholds:
Severity Limits:
informational: auto_approved
low: auto_approved
medium: auto_approved_with_monitoring
high: human_approval_required
critical: human_approval_required_escalated
System Impact Limits:
cpu_threshold: 50%
memory_threshold: 75%
network_bandwidth: 50% capacity
availability_impact: none_allowed
Data Impact Limits:
no_data_exfiltration: enforced
no_permanent_changes: enforced_with_rollback
no_credential_capture: enforced
audit_logging: always_enabled
Human-in-the-Loop Governance
Human oversight at critical decision points.
| Trigger | Approval Required | Timeline |
|---|---|---|
| Critical Vulnerability Discovery | Security team lead | 2 hours |
| High-impact Exploitation | CISO or authorized delegate | 4 hours |
| Out-of-Scope Activity Detected | Immediate halt, security review | N/A |
| Unexpected Behavior | Agent suspended, manual investigation | N/A |
| Data Access Attempt | Blocked, escalated immediately | N/A |
| Production System Testing | Security + Infrastructure team | 24 hours advance notice |
Audit & Compliance Logging
Complete audit trail for compliance and investigation.
| Log Type | Contents | Retention |
|---|---|---|
| Agent Actions | Every action taken, timestamp, result, user | 2 years |
| Finding Changes | Status changes, assignments, comments | 3 years |
| Approval Decisions | Who approved what, when, justification | 3 years |
| Scope Violations | Blocked activities, attempted out-of-scope actions | 2 years |
| System Changes | Modifications made during testing, rollback logs | 1 year |
| Access Logs | Portal access, API calls, user activity | 1 year |
API & CLI Usage
Authentication
# Set API token
export TERRA_API_KEY="tk_your_api_token_here"
export TERRA_ORG_ID="org_xxxxx"
# Or in configuration file
~/.terra/config.yaml:
api_key: tk_xxxxx
org_id: org_xxxxx
api_endpoint: https://api.terra.security
CLI Commands (Common Patterns)
# List assets
terra-cli assets list \
--scope all \
--format json
# Start a scan workflow
terra-cli scan start \
--workflow continuous \
--target 10.0.0.0/24 \
--depth 3 \
--agents asset-discovery,code-review
# Check scan status
terra-cli scan status \
--scan-id scan_xxxxx
# Get findings
terra-cli findings list \
--scan-id scan_xxxxx \
--severity critical,high \
--format json
# Generate report
terra-cli report generate \
--scan-id scan_xxxxx \
--template comprehensive \
--format pdf \
--output findings_report.pdf
# Approve exploitation
terra-cli exploit approve \
--finding-id vuln_xxxxx \
--justification "Production test window authorized"
# Manage scope
terra-cli scope update \
--add-asset tag=testing_approved \
--remove-range 192.168.1.0/24
# View agent logs
terra-cli logs \
--agent-id agent_xxxxx \
--level debug
API Endpoints (RESTful)
# Authentication
POST /api/v1/auth/token
Request: {"api_key": "..."}
Response: {"access_token": "...", "expires_in": 3600}
# List vulnerabilities
GET /api/v1/findings?severity=critical&status=open
Headers: Authorization: Bearer {token}
# Create scan
POST /api/v1/scans
Body: {"workflow": "continuous", "scope_id": "...", "depth": 3}
# Update finding status
PATCH /api/v1/findings/{finding_id}
Body: {"status": "in_progress", "assigned_to": "user_id"}
# Approve exploitation
POST /api/v1/findings/{finding_id}/approve-exploit
Body: {"justification": "...", "approved_by": "user_id"}
# Generate report
POST /api/v1/scans/{scan_id}/report
Body: {"template": "comprehensive", "format": "pdf"}
# Stream agent events (WebSocket)
WS /api/v1/agents/{agent_id}/events
Stream: {"event": "action", "action": "...", "timestamp": "..."}
Best Practices for Agentic Pentesting
Planning & Preparation
-
Define Clear Scope
- Document exact IP ranges, domains, and assets
- List explicit exclusions (production DBs, customer data)
- Specify testing windows and limitations
- Get written authorization before testing
-
Configure Agent Behavior
- Set appropriate depth levels for objectives
- Enable impact controls and rollback mechanisms
- Configure time windows to avoid peak usage
- Start conservative, increase depth gradually
-
Establish Governance
- Define approval criteria and decision-makers
- Set up escalation procedures
- Configure monitoring and alerting
- Document incident response procedures
Execution
-
Start Small
- Begin with asset discovery agents in low-depth mode
- Validate scope enforcement is working
- Review findings quality and false positive rate
- Build confidence before deeper testing
-
Monitor Continuously
- Watch real-time agent dashboards
- Review findings as they’re discovered
- Validate that agents stay within scope
- Respond immediately to anomalies
-
Leverage Copilots
- Use Copilot agents for complex exploitation
- Document guidance and recommendations
- Capture evidence systematically
- Validate findings before closing
-
Manage Findings
- Prioritize by business impact, not just severity
- Link to business context and risk tolerance
- Coordinate with development teams
- Track remediation progress
Post-Testing
-
Comprehensive Reporting
- Generate reports at appropriate detail levels
- Customize for different stakeholders
- Include actionable remediation guidance
- Schedule report distribution
-
Remediation Tracking
- Monitor finding status changes
- Re-test critical findings after fixes
- Validate compensating controls if permanent fix delayed
- Document risk acceptance decisions
-
Continuous Improvement
- Analyze agent false positive rate
- Adjust configurations based on results
- Increase automation where stable
- Maintain human oversight for complex decisions
- Share learnings with development teams
Security Considerations
-
Protect Access Credentials
- Store API keys in secure vaults
- Rotate credentials regularly
- Limit token scope to necessary permissions
- Audit API key usage
-
Maintain Audit Trails
- Enable comprehensive logging
- Archive logs for compliance retention
- Review logs periodically for anomalies
- Integrate with SIEM for correlation
-
Incident Response
- Have rollback procedures for all changes
- Document unexpected behaviors
- Maintain contact info for emergency halt
- Brief incident response teams on agent capabilities
Resources
Official Documentation & Community
| Resource | URL |
|---|---|
| Terra Security Website | https://terra.security |
| Documentation Portal | https://docs.terra.security |
| API Reference | https://api.terra.security/docs |
| Community Forum | https://community.terra.security |
| GitHub Integration | https://github.com/terra-security |
Learning & Certifications
| Program | Description |
|---|---|
| Certified Agentic Pentester | Official certification for Terra Security platform proficiency |
| Agent Configuration | Training module for workflow and agent setup |
| Exploitation Governance | Best practices for human-in-the-loop testing |
| Integration Patterns | CI/CD, ticketing, and SIEM integration training |
Blog & Articles
- “Agentic AI in Security: The Future of Pentesting” - Terra Security Blog
- “Balancing Automation with Human Oversight in Security Testing” - SANS Institute
- “From Manual to Autonomous: Scaling Security Testing” - InfoSec Magazine
Related Technologies
- OWASP Testing Guide - https://owasp.org/www-project-web-security-testing-guide
- PTES Penetration Testing Execution Standard - https://www.pentest-standard.org
- NIST Cybersecurity Framework - https://www.nist.gov/cyberframework
- CVSS Scoring - https://www.first.org/cvss
Last Updated: March 30, 2026 Platform: Terra Security Portal v2.0+ Focus: Agentic AI penetration testing with human governance Skill Level: Advanced