{"id":20329703,"url":"https://github.com/f5devcentral/f5-corkscrew","last_synced_at":"2026-01-03T19:14:34.812Z","repository":{"id":44401421,"uuid":"295139976","full_name":"f5devcentral/f5-corkscrew","owner":"f5devcentral","description":"TMOS parser and application extractor","archived":false,"fork":false,"pushed_at":"2025-01-15T19:14:04.000Z","size":9554,"stargazers_count":14,"open_issues_count":9,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-25T16:55:33.680Z","etag":null,"topics":["application-extraction","bigip","conf","corkscrew","f5-corkscrew","ltm","parse","rpm","ucs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f5devcentral.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-09-13T11:47:18.000Z","updated_at":"2024-08-19T01:14:57.000Z","dependencies_parsed_at":"2022-07-12T18:20:40.593Z","dependency_job_id":"318dcf60-55e0-49c0-a09a-2e7f48264905","html_url":"https://github.com/f5devcentral/f5-corkscrew","commit_stats":{"total_commits":138,"total_committers":3,"mean_commits":46.0,"dds":"0.021739130434782594","last_synced_commit":"3a062461b7ff335601babe72d994de1c1ac70faf"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2Ff5-corkscrew","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2Ff5-corkscrew/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2Ff5-corkscrew/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2Ff5-corkscrew/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f5devcentral","download_url":"https://codeload.github.com/f5devcentral/f5-corkscrew/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248107593,"owners_count":21048962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-extraction","bigip","conf","corkscrew","f5-corkscrew","ltm","parse","rpm","ucs"],"created_at":"2024-11-14T20:12:59.500Z","updated_at":"2026-01-03T19:14:34.806Z","avatar_url":"https://github.com/f5devcentral.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# f5-corkscrew\n\nA TypeScript-based tool for extracting and parsing F5 BIG-IP TMOS configurations from various sources (.conf, .ucs, .qkview) into structured JSON format for analysis, migration, and automation workflows.\n\n[![GitHub Release](https://img.shields.io/github/v/release/f5devcentral/f5-corkscrew)](https://github.com/f5devcentral/f5-corkscrew/releases)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n---\n\n## Features\n\n- **Multi-format Support**: Parse .conf files, UCS archives, and qkview files\n- **String Input**: Parse config directly from string (no file needed) - great for MCP servers\n- **Comprehensive Parsing**: Universal recursive parser handles all TMOS object types\n- **Discovery APIs**: List partitions and apps for efficient filtering\n- **Filtered Extraction**: Extract apps by partition or specific names\n- **Structured Output**: JSON format for easy consumption by automation tools\n- **CLI Tool**: Simple command-line interface for quick analysis\n- **Library Usage**: Import as npm package for programmatic use\n- **High Performance**: Processes large configs (6MB, 13K objects) in ~20 seconds\n- **Excellent Test Coverage**: 95.5% code coverage with comprehensive test suite\n\n---\n\n## Quick Start\n\n### Installation\n\n**Global CLI Installation:**\n```bash\nnpm install -g f5-corkscrew\n```\n\n**As Project Dependency:**\n```bash\nnpm install f5-corkscrew\n```\n\n### Requirements\n\n- **Node.js**: v22 or higher\n- **npm**: v10 or higher\n\nCheck your versions:\n```bash\nnode --version \u0026\u0026 npm --version\n```\n\n---\n\n## Usage\n\n### Command Line Interface\n\n**Basic Usage:**\n```bash\ncorkscrew --file /path/to/bigip.conf\n```\n\n**Process UCS Archive:**\n```bash\ncorkscrew --file /path/to/backup.ucs \u003e output.json\n```\n\n**Process qkview with XML stats:**\n```bash\ncorkscrew --file /path/to/diagnostics.qkview --includeXmlStats \u003e output.json\n```\n\n**CLI Options:**\n- `--file` - Path to config file (.conf, .ucs, .qkview, .tar.gz)\n- `--no_sources` - Exclude source config files from output (default: true)\n- `--no_file_store` - Exclude filestore files (certs/keys) from output (default: true)\n- `--no_command_logs` - Suppress command execution logs (default: true)\n- `--no_process_logs` - Suppress parsing logs (default: true)\n- `--includeXmlStats` - Include qkview XML statistics (default: false)\n\n### Programmatic Usage\n\n```typescript\nimport BigipConfig from 'f5-corkscrew';\n\nasync function parseConfig() {\n  const bigip = new BigipConfig();\n\n  // Load and parse config\n  await bigip.loadParseAsync('/path/to/config.ucs');\n\n  // Extract all applications\n  const explosion = await bigip.explode();\n\n  console.log(`Found ${explosion.config.apps.length} applications`);\n  console.log(`Parsed in ${explosion.stats.parseTime}ms`);\n}\n```\n\n### Parse from String (NEW)\n\n```typescript\nimport BigipConfig from 'f5-corkscrew';\n\n// Parse config from string (useful for MCP servers, APIs)\nconst configText = `#TMSH-VERSION: 15.1.0\nltm virtual /Common/app_vs {\n    destination /Common/10.0.0.1:443\n    pool /Common/app_pool\n}`;\n\nconst bigip = new BigipConfig();\nawait bigip.loadParseString(configText);\n\n// List partitions\nconst partitions = bigip.listPartitions();  // ['Common']\n\n// List apps (optionally filter by partition)\nconst apps = bigip.listApps();              // ['/Common/app_vs']\nconst tenant1Apps = bigip.listApps('Tenant1');\n\n// Extract specific apps\nconst appDetails = await bigip.apps({ partition: 'Tenant1' });\nconst specificApps = await bigip.apps({ apps: ['/Common/app_vs'] });\n```\n\n### Discovery and Filtering API\n\n```typescript\nimport BigipConfig from 'f5-corkscrew';\n\nconst bigip = new BigipConfig();\nawait bigip.loadParseAsync('/path/to/config.ucs');\n// Or: await bigip.loadParseString(configText);\n\n// Discovery - find what's in the config\nconst partitions = bigip.listPartitions();      // ['Common', 'Tenant1', 'Tenant2']\nconst allApps = bigip.listApps();               // All virtual servers\nconst tenant1Apps = bigip.listApps('Tenant1');  // Filter by partition\n\n// Lightweight summaries (good for display)\nconst summaries = bigip.listAppsSummary('Tenant1');\n// [{ name: 'app_vs', fullPath: '/Tenant1/app_vs', partition: 'Tenant1', \n//    destination: '10.0.0.1:443', pool: '/Tenant1/app_pool' }]\n\n// Filtered extraction - only dig what you need\nconst apps1 = await bigip.apps({ partition: 'Tenant1' });\nconst apps2 = await bigip.apps({ partitions: ['Tenant1', 'Tenant2'] });\nconst apps3 = await bigip.apps({ apps: ['/Common/vs1', '/Tenant1/vs2'] });\n```\n\n### Working with Output\n\n**Using jq for JSON Processing:**\n```bash\n# List all virtual servers\ncorkscrew --file config.ucs | jq '.output.config.apps[].name'\n\n# Get specific application details\ncorkscrew --file config.ucs | jq '.output.config.apps[] | select(.name == \"/Common/app1_vs\")'\n\n# Extract statistics\ncorkscrew --file config.ucs | jq '.output.stats'\n```\n\n**Example Output Structure:**\n```json\n{\n  \"output\": {\n    \"config\": {\n      \"apps\": [\n        {\n          \"name\": \"/Common/app1_vs\",\n          \"config\": \"ltm virtual /Common/app1_vs { ... }\",\n          \"map\": {\n            \"name\": \"/Common/app1_vs\",\n            \"destination\": \"192.168.1.10:443\",\n            \"pool\": \"/Common/app1_pool\"\n          }\n        }\n      ]\n    },\n    \"stats\": {\n      \"objectCount\": 153,\n      \"objects\": {\n        \"virtuals\": 7,\n        \"pools\": 7,\n        \"nodes\": 10,\n        \"monitors\": 6\n      },\n      \"parseTime\": 5478.3\n    }\n  }\n}\n```\n\n---\n\n## Supported TMOS Objects\n\nThe universal parser handles **all** TMOS object types with full depth parsing. Key objects include:\n\n### LTM (Local Traffic Manager)\n- Virtual Servers (with all nested properties)\n- Pools \u0026 Pool Members (including FQDN nodes)\n- Nodes\n- Monitors (HTTP, HTTPS, TCP, and all types)\n- Profiles (HTTP, TCP, Client-SSL, Server-SSL, and all types)\n- iRules (with proper TCL bracket handling)\n- Local Traffic Policies (LTPs)\n- Persistence Profiles\n- SNAT Pools\n- Data Groups\n- Virtual Addresses\n\n### GTM/DNS (Global Traffic Manager)\n- Wide IPs (A, AAAA, CNAME, MX, etc.)\n- Pools (all DNS record types)\n- Servers\n- Data Centers\n- Regions\n- Topology records\n\n### APM (Access Policy Manager)\n- Access Profiles\n- Access Policies\n\n### ASM/WAF (Application Security Manager)\n- Security Policies\n\n### Security\n- Bot Defense Profiles\n- DoS Profiles\n\n### System\n- Partitions and folders\n- Global settings\n- Provisioning\n- And more...\n\n---\n\n## Architecture\n\n### Core Components\n\n- **BigipConfig Class** ([src/ltm.ts](src/ltm.ts)) - Main parsing orchestrator and public API\n- **UniversalParse** ([src/universalParse.ts](src/universalParse.ts)) - Recursive TMOS parser (full-depth)\n- **UnPacker** ([src/unPackerStream.ts](src/unPackerStream.ts)) - Streams archives without full memory load\n- **DigConfigs** ([src/digConfigs.ts](src/digConfigs.ts)) - Application extraction (VS + dependencies)\n- **RegExTree** ([src/regex.ts](src/regex.ts)) - Version-specific regex patterns\n- **XmlStats** ([src/xmlStats.ts](src/xmlStats.ts)) - qkview statistics processing\n\n### Data Flow\n\n1. **Input Processing**\n   - `loadParseAsync()`: Archives streamed via UnPacker, .conf files read directly\n   - `loadParseString()`: Config text parsed directly (no file needed)\n\n2. **Universal Parsing** ([universalParse.ts](src/universalParse.ts))\n   - Recursive bracket matching handles any nesting depth\n   - iRule-aware parsing (proper TCL bracket handling)\n   - Edge cases: multiline strings, pseudo-arrays, empty objects\n   - Outputs hierarchical JSON structure\n\n3. **Discovery \u0026 Extraction**\n   - `listPartitions()`: Quick scan for unique partitions\n   - `listApps()`: List virtual servers with optional partition filter\n   - `apps()`: Full extraction with filter options\n   - `explode()`: Complete extraction of all apps + metadata\n\nSee [CLAUDE.md](CLAUDE.md) for detailed architecture documentation.\n\n---\n\n## Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/f5devcentral/f5-corkscrew.git\ncd f5-corkscrew\n\n# Install dependencies\nnpm install\n\n# Compile TypeScript\nnpm run compile\n\n# Run tests\nnpm test\n\n# Lint code\nnpm run lint\n```\n\n### Project Scripts\n\n- `npm run compile` - Compile TypeScript to JavaScript\n- `npm run watch` - Watch mode for development\n- `npm test` - Run test suite with coverage\n- `npm run lint` - Run TypeScript compiler check and ESLint\n- `npm run build-package` - Build and create npm package\n- `npm run build-code-docs` - Generate TypeDoc documentation\n\n### Testing\n\nComprehensive test suite with 95.5% coverage:\n\n```bash\n# Run all tests\nnpm test\n\n# Tests are organized by feature\ntests/\n├── 010_json_objects.test.ts      # Core object parsing\n├── 020_unPacker.tests.ts         # Archive extraction\n├── 030_dnsDetails.tests.ts       # GTM/DNS parsing\n├── 037_ltmDetails.tests.ts       # LTM parsing\n├── 040_waf.tests.ts              # ASM/WAF parsing\n└── 050_conf_file.tests.ts        # Config file processing\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Follow JSDoc documentation standards\n5. Ensure tests pass (`npm test`)\n6. Submit a pull request\n\nSee [ENHANCEMENTS.md](ENHANCEMENTS.md) for improvement opportunities.\n\n---\n\n## Performance\n\n**Typical Performance:**\n- 6MB config file\n- ~300 virtual servers\n- 223K lines\n- 13K TMOS objects\n- **Processing Time: ~20 seconds**\n\n**Memory Efficient:**\n- Streaming architecture for archives\n- Minimal memory footprint\n- Handles configs up to 50MB\n\n**Statistics Tracking:**\n- File sizes and object counts\n- Parse time breakdown\n- Performance metrics included in output\n\n---\n\n## Documentation\n\n- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes\n- **[CLAUDE.md](CLAUDE.md)** - Architecture and development guide for AI assistants\n- **[ENHANCEMENTS.md](ENHANCEMENTS.md)** - Improvement opportunities and technical debt\n- **[testingStats.md](testingStats.md)** - Performance benchmarks\n\n---\n\n## Version History\n\n### v1.6.0 (2025-12-31) - Universal Parser \u0026 MCP APIs\n- **Universal Parser**: Replaced selective parsing with full-depth recursive parser from tmos-converter\n- **String Input**: New `loadParseString()` method for parsing config text directly\n- **Discovery APIs**: New `listPartitions()`, `listApps()`, `listAppsSummary()` methods\n- **Filtered Extraction**: Enhanced `apps()` with partition and app name filters\n- **MCP-Friendly**: APIs designed for AI agent workflows (drift detection, selective extraction)\n- See [PARSER_ANALYSIS.md](PARSER_ANALYSIS.md) for technical details\n\n### v1.5.0 (2025-10-30)\n- Updated all dependencies to latest versions\n- Upgraded to Node 22 and ES2022 target\n- Major dependency updates: TypeScript 5.9.3, Mocha 11.7.4, ESLint 9.38.0\n- Improved TypeScript type safety\n- See [CHANGELOG.md](CHANGELOG.md) for complete details\n\n### Previous Versions\n- v1.4.2 - Bug fixes for partition special characters\n- v1.4.1 - Object counter bug fixes\n- v1.4.0 - VS rank nesting and UCS parsing improvements\n\n---\n\n## Support\n\n**Community Support:**\n- 📝 [GitHub Issues](https://github.com/f5devcentral/f5-corkscrew/issues) - Report bugs or request features\n- 💬 [F5 DevCentral](https://community.f5.com/) - Community discussions\n\n**Note:** This is a community-supported project and is not officially supported by F5 Networks.\n\n---\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see [LICENSE](LICENSE) file for details.\n\n---\n\n## Copyright\n\nCopyright 2014-2025 F5 Networks Inc.\n\n### F5 Networks Contributor License Agreement\n\nBefore contributing to any project sponsored by F5 Networks, Inc. (F5) on GitHub, you will need to sign a Contributor License Agreement (CLA).\n\nIf you are signing as an individual, we recommend that you talk to your employer (if applicable) before signing the CLA since some employment agreements may have restrictions on your contributions to other projects.\n\nIf you are signing on behalf of a company, you represent that you are legally entitled to grant the license recited therein.\n\n---\n\n## Community Code of Conduct\n\nPlease refer to the [F5 DevCentral Community Code of Conduct](code_of_conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff5devcentral%2Ff5-corkscrew","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff5devcentral%2Ff5-corkscrew","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff5devcentral%2Ff5-corkscrew/lists"}