ArcGIS Pro ATBX Encryption

Use this skill to automate source-code encryption for embedded Script Tools in ArcGIS Pro .atbx toolboxes. The workflow is .atbx-only. Do not redirect the user to .pyt, arcpy.EncryptPYT, or GUI-by-GUI encryption unless they explicitly change scope.

Non-Negotiables

• Use ArcGIS Pro Python on Windows.
• Use ArcGIS Pro native AfCore.dll encryption through the bundled script.
• Preserve the .atbx format; do not convert to .pyt.
• If the user provides a password in the request, use that exact password.
• If the user does not provide a password, use --generate-password --no-password-prompt so a high-entropy password is generated in memory, never printed, never stored, and not recoverable from skill outputs.
• Never assume 1234 except when reproducing the original research sample.
• Do not remove or hand-edit pw; ArcGIS Pro needs it to recognize encrypted script payloads.
• Treat this as source protection for release packaging, not secret management.

Bundled Resources

• scripts/batch_encrypt_atbx.py: batch encrypt embedded tool.script.execute.py; optionally include tool.script.validate.py.
• scripts/inspect_atbx.py: inspect one .atbx or compare plain/encrypted archives.
• scripts/validate_atbx_runtime.py: import encrypted .atbx with ArcPy, list tools, and optionally run a smoke test.
• scripts/doctor_atbx_environment.py: check ArcGIS Pro Python, arcpy, AfCore.dll, and required encryption exports.
• references/USAGE_PATTERNS.md: detailed command patterns for single files, folder releases, in-place backup, CI/CD, and dry-runs.
• references/PASSWORD_AND_SECURITY.md: password source precedence, custom password guidance, and release security boundaries.
• references/VALIDATION_AND_QA.md: structural checks, ArcPy runtime checks, acceptance criteria, and smoke-test examples.
• references/TROUBLESHOOTING.md: common failures and fixes.
• references/ATBX_ENCRYPTION_FINDINGS.md: observed GUI diff, pw behavior, native entry points, and proof summary.

Load reference files only when the current task needs those details.

Standard Workflow

1. Confirm inputs are .atbx files or folders containing .atbx files.
2. If environment is unknown, run scripts/doctor_atbx_environment.py.
3. If toolbox structure is unknown, inspect with scripts/inspect_atbx.py.
4. Choose password behavior from the user's request:
• If the user says "password is xxxx" or otherwise provides a password, including equivalent Chinese wording, pass it with --password or set a one-shot environment variable.
• If the user provides a password file or environment variable instruction, honor it.
• If the user does not provide any password, pass --generate-password --no-password-prompt; do not ask for a password unless the user explicitly wants to choose one.
5. Encrypt with scripts/batch_encrypt_atbx.py, normally to --output-dir or default _encrypted.atbx copies.
6. Validate output structurally with scripts/inspect_atbx.py.
7. Validate runtime behavior with scripts/validate_atbx_runtime.py or direct ArcPy smoke tests.
8. Report encrypted output paths, password-source method, validation status, skipped tools, and any residual risk.

Quick Commands

Run the environment doctor:

& 'C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe' `
  '.\scripts\doctor_atbx_environment.py'

Encrypt a single toolbox with a custom password from an environment variable:

$env:ARC_ATBX_PASSWORD='<custom-password>'
& 'C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe' `
  '.\scripts\batch_encrypt_atbx.py' `
  'E:\GIS_Projects\Test4CPP\testTools.atbx'

Encrypt with an explicit user-provided password:

& 'C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe' `
  '.\scripts\batch_encrypt_atbx.py' `
  'E:\GIS_Projects\Test4CPP\testTools.atbx' `
  --password '<user-provided-password>'

Encrypt without a disclosed password:

& 'C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe' `
  '.\scripts\batch_encrypt_atbx.py' `
  'E:\GIS_Projects\Test4CPP\testTools.atbx' `
  --generate-password `
  --no-password-prompt

Batch encrypt a release folder:

$env:ARC_ATBX_PASSWORD='<custom-password>'
& 'C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe' `
  '.\scripts\batch_encrypt_atbx.py' `
  --root 'E:\GIS_Projects\Test4CPP\toolboxes' `
  --output-dir 'E:\GIS_Projects\Test4CPP\release' `
  --no-password-prompt

Inspect encrypted output:

& 'C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe' `
  '.\scripts\inspect_atbx.py' `
  'E:\GIS_Projects\Test4CPP\release\testTools.atbx'

Validate ArcPy import and optionally run a tool:

& 'C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe' `
  '.\scripts\validate_atbx_runtime.py' `
  'E:\GIS_Projects\Test4CPP\release\testTools.atbx' `
  --alias enc `
  --run-tool Script `
  --params-json '[]'

Decision Rules

• If the tool links to an external .py and no embedded tool.script.execute.py exists, explain that the release pipeline must embed script code in the .atbx first.
• If output exists, use --overwrite only when the user explicitly accepts replacing release outputs.
• If source files must be replaced, use --in-place with backups unless the user explicitly disables backups.
• If a toolbox already has pw, skip by default; use --force only for intentional re-encryption.
• If validation code must be hidden too, pass --include-validation and validate parameter UI/runtime behavior afterward.
• If ArcPy import succeeds but tool execution fails, treat it as a tool/runtime-parameter problem unless structural checks fail.
• If the report says password_source is generated:undisclosed, do not claim that the password can be recovered. The encrypted tool can run, but source viewing/editing with a password is intentionally unavailable.

Success Criteria

• Each encrypted Script Tool has pw in tool.content.
• Each encrypted execution script starts with ArcGIS-recognized encrypted text such as 00022e68.
• Original Python source is no longer directly readable from the script entry.
• ArcPy can import the encrypted .atbx.
• Representative tools run with known-safe parameters.
• Unencrypted source and backups are excluded from release artifacts.