Pre-upgrade scanner for ForgeRock / Ping Identity Gateway. Detects compatibility issues in your IG configuration before you migrate to PingGateway 2024.11 / Groovy 4.
What it does
Scans an IG configuration directory and reports:
- Groovy 4 breaking changes — removed classes (XmlSlurper, AntBuilder, GroovyTestCase, etc.), wildcard imports, behavior shifts (intersect, getProperties, 0.0f equality).
- PingGateway API deprecations — blocking
Promise.get() calls, deprecated request.form, JwtSession, TokenResolver, _token(), LdapClient, org.forgerock.util.time.Duration, and more.
- Route JSON config issues — duplicate keys, missing required config fields (
UserProfileFilter / AmService / etc.), duplicate route names, deprecated matches() in conditions and ${...} expressions.
- Cross-file integrity — orphan scripts (no route references them) and dangling references (route points to a nonexistent script).
- Security & path concerns — hardcoded credentials,
secret.id literal values, Tomcat-era paths, absolute filesystem paths that may not survive migration.
Output channels:
- HTML report — embedded in a webview panel; export to a standalone file for audit / email distribution.
- VSCode Problems panel + inline red/yellow/blue squiggles — click any issue to jump to the offending line.
- Activity Bar tool launcher — the IAM Toolkit icon hosts the IG Upgrade Analyzer (and future tools).
Usage
- Click the IAM Toolkit icon in the Activity Bar.
- Click IG Upgrade Analyzer — the tool panel opens in the editor area.
- Click Browse… to pick your IG configuration directory (e.g.
~/openig/ containing config/ and scripts/).
- Click Run scan.
Results appear in three places simultaneously:
- The HTML report inside the tool panel
- The Problems panel (auto-opens if any issues found — toggle in Settings)
- Red/yellow/blue squiggles in any open
.groovy or route .json file
Alternative entry points:
Cmd+Shift+P → IAM Toolkit: Run IG Upgrade Scan- Right-click any folder in the Explorer → Run IG Upgrade Scan (auto-runs on the chosen folder)
Settings
Configure via Cmd+, → search "IAM Toolkit", or via the Settings panel inside the tool itself:
| Setting |
Effect |
iamToolkit.igUpgrade.disabledRules |
List of rule IDs to skip during scan (e.g. ["G4-201", "PATH-102"]). |
iamToolkit.igUpgrade.ignorePaths |
Absolute path prefixes to ignore for PATH-102 (e.g. ["/opt/logs", "/var/log"]). |
iamToolkit.igUpgrade.autoOpenProblems |
Auto-open the Problems panel after a scan if any issues are found. Default true. |
All settings persist via VSCode workspace settings; they sync via Settings Sync and travel with .vscode/settings.json.
Rule reference
See the full rule specification at docs/ig-upgrade-rules.md. All 36 rules across 7 categories are documented with severity, intent, and remediation guidance.
Roadmap
- v0.1 (current): IG Upgrade Analyzer with full Python-equivalent rule set.
- v0.2: Quick fixes (one-click migration of removed imports, deprecated APIs).
- Future: additional IAM ops tools — DS / AM / IDM Upgrade Analyzers, runtime helpers.
Building from source
git clone <repo-url>
cd iam-toolkit-vscode
npm install
npm run compile # one-shot
npm run watch # incremental during dev
npm run package # produce iam-toolkit-<version>.vsix
Press F5 in VSCode to launch an Extension Development Host with the extension loaded.
License
MIT — see LICENSE.
