What Is the Scope Contract and Why Is It Required Before Target Analysis?

The scope contract is a machine-readable agreement stored in ops/scope-contract.md that explicitly defines authorization status, network boundaries, and asset inclusions, and it must be validated before target analysis to ensure legal compliance and prevent unauthorized access.

In the zhaoxuya520/reverse-skill repository, the scope contract functions as the foundational guardrail for all security engagements. This mandatory document establishes the precise legal and technical boundaries that every skill must verify before executing any reconnaissance, testing, or analysis operations.

The Four Essential Elements of a Scope Contract

The scope contract captured in ops/scope-contract.md contains four mandatory fields that collectively define the engagement perimeter.

Authorization Status

The auth.status field records whether the client or program has granted explicit permission, typically set to granted or denied. This element serves as the primary legal checkpoint, guaranteeing that analysts possess documented authorization before proceeding. Every skill in the repository checks this field first, and any value other than granted triggers an immediate workflow abort.

Network Profile

The network_profile specifies allowed network zones, IP ranges, VPN usage requirements, and restrictions on Internet access. This configuration prevents analysts from inadvertently routing traffic through prohibited gateways or exposing internal production networks during testing phases.

In-Scope Assets

The in_scope.assets field provides a concrete, enumerated list of domains, IPs, binaries, mobile apps, APIs, or hardware approved for active examination. As documented in skills/pentest-tools/SKILL.md, skills parse this list to validate targets before executing any offensive actions, ensuring testers never deviate from authorized systems.

Out-of-Scope Exclusions

The out_of_scope field explicitly forbids specific activities or systems, such as denial-of-service attacks, production environments, or third-party services. These exclusions protect against collateral damage and legal liability, with skills/threat-intelligence/SKILL.md referencing these boundaries during public data gathering to ensure no prohibited systems are researched.

Why Target Analysis Requires a Validated Scope Contract

Analysis workflows enforce a strict "scope-first" discipline where the contract must exist and pass validation checks before any data collection or testing begins.

Legal and Ethical Guardrails

The contract serves as the single source of truth for what analysts are legally permitted to do under specific engagement terms. According to the repository's routing logic in skills/routing.md, if ops/scope-contract.md is missing or auth.status is not set to granted, skills immediately terminate and emit critical warnings rather than risk unauthorized access. This enforcement mechanism satisfies compliance frameworks and ethical hacking standards.

Evidence Discipline and Audit Trails

All evidence generated during analysis links back to the scope contract via the workflow defined in ops/timeline-workitem.md. This linkage creates an immutable audit trail that connects every finding and artifact to the original authorization parameters. Without the contract establishing this context, evidence lacks the legal foundation required for formal reporting or court proceedings.

Automated Tool Safety

Automated tools and bootstrapping scripts read the contract to self-limit their operational parameters. For instance, scripts/case-init.sh refuses to initiate mass-scanning activities unless in_scope.assets contains valid entries and out_of_scope exclusions have been explicitly reviewed. This prevents automated scanners from accidentally targeting prohibited infrastructure or exceeding network boundaries.

Operational Consistency

As the central component of the Ops contract architecture, the scope contract drives routing, bootstrapping, and case-guard logic across all skill modules. Whether using skills/radio-sdr/SKILL.md for radio frequency analysis or threat intelligence tools, the same boundary definitions apply universally, ensuring consistent security posture across disparate testing methodologies.

How Skills Enforce Scope Contract Validation

Skills implement mandatory validation logic at initialization to ensure the scope contract exists and authorizes the specific requested activity.

Bash Validation Pattern

Shell-based skills use the following pattern to abort execution when the contract is invalid:

#!/usr/bin/env bash
CONTRACT=../ops/scope-contract.md

# Abort if the contract does not exist or auth is not granted

if [[ ! -f "$CONTRACT" ]] || ! grep -q "auth.status *= *granted" "$CONTRACT"; then
    echo "❌ No valid scope contract – aborting."
    exit 1
fi

# Parse in-scope assets (example using yq if the contract is YAML)

IN_SCOPE=$(yq '.in_scope.assets[]' "$CONTRACT")
echo "🔍 In-scope targets: $IN_SCOPE"

PowerShell Validation Pattern

Windows-based skills implement equivalent guards using PowerShell syntax:

$contractPath = "..\ops\scope-contract.md"
if (-Not (Test-Path $contractPath)) {
    Write-Error "Scope contract missing – stop."
    exit 1
}

$content = Get-Content $contractPath -Raw
if ($content -notmatch "auth\.status\s*=\s*granted") {
    Write-Error "Auth not granted – abort."
    exit 1
}

# Extract a list of in-scope hosts (simple regex example)

$inScope = ($content -match "in_scope\.assets\s*=\s*\[(.*?)\]") | Out-Null
Write-Host "🛡️  In-scope assets: $($Matches[1])"

Node.js Validation Pattern

MCP tools and Node-based skills read and parse the contract using JavaScript:

const fs = require('fs');
const path = '../ops/scope-contract.md';

if (!fs.existsSync(path)) {
    console.error('Scope contract missing – abort');
    process.exit(1);
}

const contract = fs.readFileSync(path, 'utf8');
if (!/auth\.status\s*=\s*granted/.test(contract)) {
    console.error('Auth not granted – abort');
    process.exit(1);
}

// Simple extraction of in-scope domains
const assets = contract.match(/in_scope\.assets\s*=\s*\[(.*?)\]/);
console.log('📍 In-scope assets:', assets?.[1] ?? 'none');

Summary

• The scope contract in ops/scope-contract.md defines the legal and technical boundaries for all security engagements in the repository.
• Four critical elements—authorization status, network profile, in-scope assets, and out-of-scope exclusions—must be documented and validated before any analysis begins.
• Skills automatically halt execution if the contract is missing or if auth.status is not granted, preventing unauthorized access and legal violations.
• The contract creates an auditable evidence chain through ops/timeline-workitem.md, linking all findings to authorized scope parameters.
• Bootstrapping tools like scripts/case-init.sh rely on the contract to self-limit network activity and prevent accidental targeting of prohibited systems.

Frequently Asked Questions

What happens if a skill runs without a valid scope contract?

Any skill executing in the zhaoxuya520/reverse-skill repository will immediately abort and emit a critical error if ops/scope-contract.md is missing or if the auth.status field does not equal granted. This hard stop prevents analysts from accidentally conducting unauthorized testing that could violate computer fraud laws or damage third-party systems.

How does the scope contract protect against network security risks?

The contract's network_profile and out_of_scope fields explicitly define prohibited network zones and forbidden attack types, while initialization scripts validate these settings before allowing any packets to leave the analysis host. This architecture ensures automated enumeration tools cannot route traffic to prohibited infrastructure or execute denial-of-service attacks against production systems.

Which repository components reference the scope contract?

The contract is referenced by skills/threat-intelligence/SKILL.md for intelligence gathering boundaries, skills/pentest-tools/SKILL.md for target validation, skills/radio-sdr/SKILL.md for transmission restrictions, and skills/routing.md for operational workflow logic. Additionally, ops/timeline-workitem.md uses the contract to maintain proper audit trails across case transitions.

Can the scope contract be modified during an active analysis?

While the file structure supports updates, modifying scope boundaries during active analysis requires re-validation through the case-init workflow and updated authorization status. Skills generally read the contract at initialization and cache its state, meaning changes mid-analysis require restarting the skill process to ensure all components recognize and enforce the new boundaries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}