Skip to content

validate_paths

Validate that file paths are accessible and within allowed boundaries. Essential for Docker deployments and sandboxed environments.

Quick Reference

validate_paths(
    paths: list,                 # Paths to validate
    project_root: str = None     # Project root directory
) -> PathValidation

User Stories

Persona Story Tool Value
🏢 Jennifer (Enterprise Architect) "Pre-validate file access permissions before analysis" Security boundaries
🔧 Chris (OSS Contributor) "Verify paths are accessible in Docker deployments" Deployment validation
👥 David (Team Lead) "Ensure analysis tools only access approved directories" Access control

→ See all user stories

Parameters

Parameter Type Required Default Description
paths list[string] Yes - List of paths to validate
project_root string No cwd Project root directory

Response Schema

{
  "data": {
    "results": [
      {
        "path": "string",
        "exists": "boolean",
        "accessible": "boolean",
        "within_project": "boolean",
        "is_file": "boolean",
        "is_directory": "boolean",
        "error": "string | null"
      }
    ],
    "all_valid": "boolean",
    "summary": {
      "total": "integer",
      "valid": "integer",
      "invalid": "integer"
    }
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples

Validate Multiple Paths

Check if these files exist and are accessible:
- src/main.py
- config/settings.json
- logs/app.log

{
  "paths": [
    "/project/src/main.py",
    "/project/config/settings.json",
    "/project/logs/app.log"
  ],
  "project_root": "/project"
}

codescalpel validate-paths src/main.py config/settings.json logs/app.log

{
  "data": {
    "results": [
      {
        "path": "/project/src/main.py",
        "exists": true,
        "accessible": true,
        "within_project": true,
        "is_file": true,
        "is_directory": false,
        "error": null
      },
      {
        "path": "/project/config/settings.json",
        "exists": true,
        "accessible": true,
        "within_project": true,
        "is_file": true,
        "is_directory": false,
        "error": null
      },
      {
        "path": "/project/logs/app.log",
        "exists": false,
        "accessible": false,
        "within_project": true,
        "is_file": false,
        "is_directory": false,
        "error": "File does not exist"
      }
    ],
    "all_valid": false,
    "summary": {
      "total": 3,
      "valid": 2,
      "invalid": 1
    }
  },
  "tier_applied": "community",
  "duration_ms": 15
}

Check Directory Access

Verify I can access the src and tests directories

{
  "paths": [
    "/project/src",
    "/project/tests"
  ]
}

codescalpel validate-paths src/ tests/

{
  "data": {
    "results": [
      {
        "path": "/project/src",
        "exists": true,
        "accessible": true,
        "within_project": true,
        "is_file": false,
        "is_directory": true
      },
      {
        "path": "/project/tests",
        "exists": true,
        "accessible": true,
        "within_project": true,
        "is_file": false,
        "is_directory": true
      }
    ],
    "all_valid": true
  }
}

Detect Path Traversal Attempt

Check if ../../../etc/passwd is accessible

{
  "paths": [
    "/project/../../../etc/passwd"
  ],
  "project_root": "/project"
}

codescalpel validate-paths "../../../etc/passwd"

{
  "data": {
    "results": [
      {
        "path": "/project/../../../etc/passwd",
        "exists": true,
        "accessible": false,
        "within_project": false,
        "is_file": true,
        "error": "Path is outside project root (path traversal detected)"
      }
    ],
    "all_valid": false,
    "security_warning": "Attempted path traversal detected"
  }
}

Docker Volume Check

In Docker, check if the mounted workspace is accessible

{
  "paths": [
    "/workspace",
    "/workspace/src",
    "/app/config"
  ]
}

codescalpel validate-paths /workspace /workspace/src /app/config

{
  "data": {
    "results": [
      {
        "path": "/workspace",
        "exists": true,
        "accessible": true,
        "is_directory": true
      },
      {
        "path": "/workspace/src",
        "exists": true,
        "accessible": true,
        "is_directory": true
      },
      {
        "path": "/app/config",
        "exists": false,
        "accessible": false,
        "error": "Directory does not exist (volume may not be mounted)"
      }
    ],
    "all_valid": false,
    "docker_hint": "Ensure all required volumes are mounted in docker-compose.yml"
  }
}

Validation Checks

Check Description
exists Path exists on filesystem
accessible Current user can read path
within_project Path is inside project root
is_file Path points to a file
is_directory Path points to a directory

Error Types

Error Cause
"File does not exist" Path doesn't exist
"Permission denied" No read access
"Path is outside project root" Path traversal attempt
"Not a valid path" Invalid characters
"Symlink to outside project" Symlink escape

Tier Differences

This tool is available at all tiers. What differs are the limits and capabilities:

Feature Community Pro Enterprise
Availability ✅ Available ✅ Available ✅ Available
Basic validation ✅ ✅ ✅
Project root check ✅ ✅ ✅
Path traversal detection ✅ ✅ ✅
Symlink validation Not available ✅ ✅
Docker hints Not available ✅ Volume checks ✅ Advanced

Use Cases

1. Pre-Operation Check

# Before any file operation, validate paths
paths_to_check = [input_file, output_file, config_file]
result = validate_paths(paths=paths_to_check)

if not result.all_valid:
    for r in result.results:
        if r.error:
            print(f"Error with {r.path}: {r.error}")

2. Docker Deployment

# Verify Docker volumes are correctly mounted
result = validate_paths(
    paths=["/workspace", "/workspace/src", "/config"],
    project_root="/workspace"
)

if not result.all_valid:
    raise RuntimeError("Docker volumes not properly mounted")

3. Security Boundary

# Prevent access outside project
user_requested_path = f"/project/{user_input}"
result = validate_paths(
    paths=[user_requested_path],
    project_root="/project"
)

if not result.results[0].within_project:
    raise SecurityError("Access denied: path outside project")

Tier Limits

validate_paths capabilities vary by tier:

Feature Community Pro Enterprise
Max paths 100 Unlimited Unlimited
Basic validation ✅ ✅ ✅
Permission checks Basic ✅ Full ✅ Full
Symlink resolution ✅ ✅ ✅
Docker-aware ✅ ✅ ✅ Enhanced
Error suggestions Basic ✅ Detailed ✅ Auto-fix

Community Tier

  • ✅ Validate up to 100 file paths
  • ✅ Check if files exist and are accessible
  • ✅ Basic permission checks (readable, writable)
  • ✅ Symlink resolution
  • ✅ Docker-aware path validation
  • ⚠️ Limited to 100 paths - Small projects only
  • ❌ Limited error suggestions

Pro Tier

  • ✅ All Community features
  • ✅ Unlimited paths - Validate entire project
  • ✅ Full permission checks - Execute, owner, group permissions
  • ✅ Detailed error suggestions - Help fix path issues
  • ✅ Enhanced Docker validation - Better container support

Enterprise Tier

  • ✅ All Pro features
  • ✅ Auto-fix suggestions - Generate commands to fix issues
  • ✅ Network path validation - Validate remote paths
  • ✅ Security policy enforcement - Enforce path access rules
  • ✅ Audit trail - Track path validation history

Key Difference: Path Coverage and Error Handling - Community: 100 paths, basic validation - Small projects - Pro: Unlimited, detailed errors - Production path validation - Enterprise: Unlimited, auto-fix, policies - Enterprise path management

→ See tier comparison

Best Practices

  1. Always validate user input - Before file operations
  2. Use absolute paths - Avoid ambiguity
  3. Check before operations - Fail fast with clear errors
  4. Set project_root - Enable boundary checking
  5. Check in Docker - Verify volume mounts