Source Code Delivery Instructions

Document version 2-7 — 03 March 2022

The informational material contained in this section is provided as a courtesy for use by CAST’s clients. Licensing details are documented here: https://www.gnu.org/licenses/lgpl-3.0.en.html.

The official CAST AIP technologies documentation is published here.

Introduction

Recommendation

The delivery structure must correspond to your project structure and must be reproducible, to allow for consistency during subsequent analysis. Ask your development team to produce a standard export from the code repository (for example, git clone).

The CAST AIP analysis platform performs a static analysis of the source code and builds a model of the application to verify its structural quality. To perform the analysis, you must deliver all the elements necessary for compilation of the code generated upstream for the application:

Files written by developers or generated by the IDE (project files, source, …).
Code files generated during compilation (e.g. generated services), so that all components of the production system are present.
Generated code must be structured at the time of delivery, and the identification methods defined (naming rule, directory, etc.).
Third-party libraries and the files that reference them (pom.xml, …).

Note

CAST will not retrieve third-party libraries from public/private repositories (Maven, npm, pip, NuGet …), and the code will not be compiled by CAST.

Files to exclude

Exclude files that should not be scanned, for example:

Test code.
HTML / JS files generated by documentation-generation or analysis tools.
Large data files included in your deployment but not required for the structure of the application (e.g. videos or images included in a CRM).

SQL databases

For SQL databases, provide only one DDL script per schema:

Incremental database definitions are not supported.
Each file must start with the instruction to create the schema, with a name specific to the schema (identifiable by the developers).
The script must contain all the elements that make up the schema (tables, fields, integrity constraints, indexes, stored procedures, etc.) but no data (no INSERT or UPDATE).
(Optional) You may be asked for the size statistics of the tables in production, in order to modulate the recommendations according to the volumes of data stored.
(Optional) You may be asked to deliver unit-test code-coverage reports.

Delivery structure

The delivery should consist of a single zip file, with a structure similar to the one in this illustration:

Example delivery structure

Details per technology

The sections below detail the files expected for an analysis. Please contact the project manager if you are unsure whether a type of file is suitable for static analysis. Expand each technology to see its requirements.

Minified / bundled files

For JavaScript and HTML5, send the files in a “normal” format rather than a minified or bundled format. Minified files (e.g. *.min.js) and bundled files that contain one or a few very long lines are automatically excluded from the analysis.

C / C++

Show file requirements

Requirement	CAST comment
All source files of the application, including project files. Typical extensions: `.c`, `.cpp`, `.cxx`, `.pc`… and for includes: `.h`, `.hh`, `.hpp`, `.tpp`, `.inl`, `.inc`…	Avoid delivering `.lib`, `.a`, `.obj`, `.so`, `.dll`, `.exe`… (libraries and executable files).
The system headers of the operating system and compiler with which the source code is compiled.
The external (third-party) library headers.	Use the header files that are consistent with the chosen operating system (those installed on the OS used to build the application).
All makefiles.	All files used by the build system (autoconf, cmake, makefiles, vcxproj, xcodeproj…).
Build log files.	Only for non-Microsoft compilers. The compiler log files make it easier to detect the macros used for compilation and the include paths.
Include path.
The set of hard-coded macros defined by the compiler.	May depend on compiler options. Provide the set corresponding to the options used to build the executables and libraries.
Macros passed as compiler or build options.	For instance, macros can be passed on the command line as parameters (`-DMACRO=value`).
Executables and libraries organisation.	Provide information on the source code used to build the executables and libraries, as well as their dependencies.
Database access API.	Which databases the C/C++ code relies on and their versions, and how the code interacts with the database: through embedded SQL (like PRO*C), or using the database standard API (OCI/OCCI for Oracle, ODBC for SQL Server, CT-LIB for Sybase…).
Dynamic code.	Is there any dynamic code (dynamic libraries)? What are the API calls for loading the dynamic libraries and executing the dynamic code?

Adobe (Flex)

Show file requirements

Requirement	Comment
The source code must be in a file/folder structure that is able to be compiled. Allowable file extensions: `.as`, `.mxml`.	Source code often refers to include files or other layers’ executables with a relative path, so the relative paths must be respected in the delivery folder structure.

Fortran

Show file requirements

Requirement	Comment
The source code must be in a file/folder structure that is able to be compiled.	Source code often refers to include files or other layers’ executables with a relative path, so the relative paths must be respected in the delivery folder structure.
Allowed FORTRAN file extensions: `.for`, `.FOR`, `.inc`, `.INC`, `.pfo`, `.PFO`, `.f`, `.F`, `.f03`, `.F03`, `.f90`, `.F90`, `.f77`, `.F77`, `.h`.

Java JEE

Show file requirements

Requirement	Comment
All the source files of the application (all `.java` files), including project and configuration files, for example: `.xml` files used by frameworks `.properties`, `.json`, `.yml` files EJB configuration files and all their deployment mapping files All associated deployment mapping files (required to link with the database) `web.xml` for each web application All `.jsp` / `.jcx` / `.jspf` / `.jhtml` and similar files All `.xsl` files All tag libs (`.tld`) All XML configuration files (`struts-config.xml`, …) and mapping files All DTD files associated with the XML files All HTML files All JavaScript files All CSS (image files can be removed) For web services: WSDL / WSDD / mapping files TLD documentation	All source code must be encoded in ASCII or a supported Unicode encoding (UTF-8, …). Supported encoding/character sets are listed in Supported Character Sets. Ensure you collect the `.java` files, not `.class` or `.jar` files, for source code within the scope of the analysis. `.class` and `.jar` files are decompiled only to extract the signature.
Build configuration files: Maven and/or Eclipse project files: `.pom`, `.project`, `.classpath` Gradle For information only, Ant and Ivy scripts should be delivered but will not be analyzed automatically	Including the complete hierarchy of ALL `.pom` and parent `.pom` files. These allow automated discovery and analysis configuration.
All libraries (`.jar`) required to build the application, including JDK, JEE and related libraries (application server, third party, framework, presentation, persistence, etc.). For a Maven project, provide a copy of the local Maven repository.	Custom JAR files (e.g. custom `J2EE.jar` used for presentation and persistence) should be delivered with the source code. Failure to do so will prevent transaction identification and all dependent metrics.
`.jar` files. `.war` and `.ear` files should not be delivered.	Required to reproduce the real production structure with the sources.
If some SQL files remain in the source delivery, explain how to deal with them.	Normally a database must be extracted as DDL files and delivered as SQL files in a specific folder/zip.
Files that contain data are useless (`.dat`, `.doc`, `.ppt`, `.xls`, `.xml` that contains data only).	These files are big, not required and not analyzed, so there is no need to provide them.

Notes:

A copy of the local Maven repository is not mandatory; only the JAR files in a repository that are actually used by the project are mandatory.
Exclude .git and .svn folders.

Message Queues

Covers: ActiveMQ (Java, Python), IBM MQ (Java, Python), RabbitMQ (Java, Python), Spring JMS, Spring AMQP.

Show file requirements

Technology	Requirement	Comment
ActiveMQ (Java, Python)	All configuration files	In addition to the provided application files
IBM MQ (Java, Python)	All configuration files
RabbitMQ (Java, Python)	All configuration files
Spring JMS	All configuration files
Spring AMQP	All configuration files

Mobile

Covers: Android, iOS/Objective-C, iOS/Swift, Ionic, React Native.

Show file requirements

Technology	Requirement	Comment
Android	All application files + configuration files
iOS / Objective-C	All application files + configuration files
iOS / Swift	All application files + configuration files
Ionic	Source code before compilation. File extensions are `.ts`, `.html`, `.css` or `.scss`.	Source code written by developers is mandatory.
React Native	Source code before compilation. File extension is `.js` only.	Source code written by developers is mandatory. If there is another specific file extension, it must be clarified by the customer.

IBM Mainframe zOS (Cobol, JCL, CICS)

Show file requirements

Option 1 — Export of the PDS

Requirement	Comment
Export of the PDS (when the programs are members of a Partitioned Data Set).	Use `IEBPTPCH` to print and punch the PDS (1 PDS per type of source code) before transfer to the PC. See the Partitioned Data Set (PDS) section of Mainframe – application qualification specifics.
All the source code must be in ASCII format.	If files are not in ASCII format, or CR/LF are not readable, the Mainframe Analyzer will not be able to analyze them.
TRANSACTION (`.CSD` and `.BMS`).	`.CSD`: this resource definition can be delivered as a copy (into an ASCII flat file) of the script used to define the CICS environment, or by using a JCL to extract this information from CICS. See an example JCL to extract the CSD, and a sample JCL using the IBM utility DFHCSDUP, at On-line processing. `.BMS`: description of the mapset.

Option 2 — One file per object type

Each application must be delivered in a single folder, with one file per object type (1 file per program, 1 per copybook, 1 per JCL job, etc.) in the folder structure shown below. All the source code must be in ASCII format — if files are not in ASCII format, or CR/LF are not readable, the Mainframe Analyzer will not be able to analyze them.

Mainframe delivery folder structure

Each application folder must contain sub-folders split by technology:

Sub-folder	Contents
COBOL	Cobol programs and copybooks
BATCH	JCL jobs, JCL includes, JCL procedures
TRANSACTION	`.CSD`: delivered as a copy (into an ASCII flat file) of the script used to define the CICS environment, or via a JCL to extract it from CICS (see the sample JCL using DFHCSDUP at On-line processing). `.BMS`: description of the mapset.
IMS	IMS database description (DBD) as a text file; PSB files including all the PCBs of the application

Allowable file extensions:

Source type	Extensions
COBOL programs	`.cbl`, `.cob`, `.cobol`
Copybook files	`.cpy`, `.copy`
IMS files	`.psb`, `.dbd`
CICS files	`.csd`, `.bms`
JCL jobs	`.jcl`
JCL procedures	`.prc`, `.proc`
JCL includes	`.inc`

EGL

Show file requirements

Requirement	Comment
All EGL program files must be under one folder structure. Permitted file extensions: `.egl`, `.egldd`, `.eglbld`, `.project`.	The sub-directory structure can reflect the application organization.

Microsoft .NET

Show file requirements

Files to deliver — all artefacts required to build the system, including:

Project files: .sln, .csproj, .vbproj
.NET code files: .cs, .vb
GUI files:
- ASP.NET applications: .aspx, .ascx
- ASP.NET MVC applications: .cshtml, .vbhtml
- WPF applications: .xaml
Additional assets: for instance .htm, .html, .css, .js
Configuration files: .config, .properties; for Entity Framework: .edmx (if applicable)
Third-party libraries — assemblies used by the application that are not part of the .NET Framework: .dll; for COM/ActiveX components: .ocx

General guidelines

Usually, source code is versioned using a CMS (tools like SVN or Git).
The best way to deliver source code is to check out, from the CMS, the version selected for analysis. Make sure not to include the .git or .svn folders.
Third-party libraries:
- If dependencies are managed via NuGet, they are located in one or more packages folders → zip those folders.
- Alternatively, provide a zip with the compiled version of the application (the application’s assemblies and the external assemblies).

Example

Given the organization pictured below, the full content of the “Sample .NET Application” folder must be provided, except:

The .git folder: related to the CMS used by the development team (here, Git).
The obj folders: they contain temporary/intermediate artefacts generated during the build process.

To deliver third-party assemblies, the bin and/or packages folders may be included in the delivery:

bin folders contain binaries (debug and/or release assemblies) created at build time; they should also contain third-party assemblies.
packages folders are created by the NuGet package manager and contain assemblies and artefacts published in a NuGet repository.

Sample .NET application structure

Microsoft (not .NET)

Covers: ASP, VB.

Show file requirements

ASP

Requirement	Comment
All the source code must be encoded in ASCII or a supported Unicode encoding (e.g. UTF-8).	Supported encoding/character sets are listed in Supported Character Sets.
All `.asp` / `.inc` ASP pages of the web application.	Including included files (`.inc`).
All `.asa` / `.htm` / `.html` / `.htc` / `.css` / `.vbs` files.
All `.htm` / `.html` / `.js` / `.vbs` files.	Client code.
All `.gif` / `.bmp` / `.png` / `.jpg` / `.jpeg` files.	Images used by the application.
COM objects used by the above pages: `.ocx`, `.dll`, `.exe`.	Components for which you don’t have the source, including third-party components.

Requirement	Comment
All the source code must be encoded in ASCII or a supported Unicode encoding (e.g. UTF-8).	Supported encoding/character sets are listed in Supported Character Sets.
Projects: `.vbp`.
Groups: `.vbg` (if any).
All source code referenced by the projects: `.bas`, `.frm`, `.cls`, `.ctl`…	Including third-party components.
COM objects used by the application: `.ocx`, `.dll`, `.exe`.	Components for which you don’t have the source, including third-party components.

Oracle Enterprise Solutions

Covers: Oracle Forms/Reports, PeopleSoft, Siebel.

Show file requirements

Oracle Forms / Reports

DMT’s Oracle Forms and Reports option must be used for extraction.

Oracle Forms: .FMB, .OLB, .MMB, .PLL
Oracle Reports: .REX

PeopleSoft

To download the PeopleSoft extractor, go to CAST Extend: https://extend.castsoftware.com/V2/. The extractor is composed of the following elements:

CASTDBGUI.jar
CASTPeopleSoft_db2.config
CASTPeopleSoft_orcl.config
PeopleSoft-Extract-CLI.bat — every row with <PARAM> should be filled with the right parameter (path, DB name, …)

The following should be delivered to CAST:

Extraction of the Vanilla environment
Extraction of the Project environment
DDL of the database

The specific code in PeopleSoft is not detectable on its own — it is mixed with the PeopleSoft code. To analyze the specific code, CAST compares the original PeopleSoft code (called Vanilla) with the PeopleSoft code plus the specific code (called Project). The two environments must be exactly the same release, and both extractions must be done with the CAST PeopleSoft extractor.

Siebel

The CAST SIEBEL extractor must be used for source code extraction.

PHP

Show file requirements

Requirement	Comment
All the `.html`, `.htm`, `.phtml`, `.php`, `.php4`, `.php5`, `.php6`, `.inc`, `.js` and `.css` files of the application.	The analysis of XML and XSL files contained in the PHP application is not supported (those files can still be delivered). The analysis of HTML and JavaScript source code is handled by the JEE or the new .NET analyzer, to be configured in addition to the generated UA for the PHP job.
All `.gif`, `.bmp`, `.png`, `.jpg`, `.jpeg`, `.tiff` files.	Images used by the application.

For PHP, specify the framework used (Symfony, Drupal, Joomla, etc.).

IBM PL/1

Show file requirements

Requirement	Comment
Each file must contain only a single artefact or component.	A file can only contain a PL/1 program or a single include file.
DB2 table definitions must be exported to include files (`.PLC` extension).	The `EXEC SQL INCLUDE` statements referring to include files generated by DB2 for PL/1 are targeted.
The type of source code must be identifiable using the file extension.
All PL/1 program files must be under one folder structure.	The sub-directory structure can reflect the application organization. All include files must be under a PLC directory. All table-definition files must be under a TLC directory.
PL/1 programs must have `.PLI` extensions.
Include and table-definition files must have `.PLC` extensions.

Python

Show file requirements

Requirement	Comment
The Python source code, delivered with the file extension `.py`.
Python dependencies: the file listing the dependencies (`requirements.txt`).

IBM System i

Covers: RPG, Cobol AS400, DataStage.

Note: some artefacts, such as Physical Files (.PF) and Logical Files (.LF), are used by COBOL for AS400 but are parsed by the RPG extension. Some links may be added from COBOL.

Show file requirements

Technology	Requirement	Comment
RPG	Each application must be delivered in a single folder, with sub-folders split by technology: RPG programs from the QRPGSRC library → `.RPG` (RPG-III), `.RPGLE`, `.SQLRPGLE` COPY RPG from QCPYSRC (for RPG and CL programs) → `.CPYRPG`, `.CPYCLP` CL programs from QCLPSRC → `.CLLE`, `.CLP` Display files from QDSPSRC → `.DSPF` Printer files from QRPTSRC → `.PRTF` Logical (LF) and Physical (PF) files from QDDSSRC → `.LF`, `.PF`	For the complete list of file extensions, see the RPG extension documentation. Extract the source code from the AS400 libraries. The QCPYSRC library can contain copies for RPG, CL and COBOL programs.
Cobol AS400	Each application must be delivered in a single folder, with sub-folders split by technology: COBOL programs from QCBLSRC → `.CBL`, `.SQLCBL`, `.SQLCBLPCML`, `.SQLCBLLET`, `.SQLCBLLEC` COPY COBOL from QCPYSRC → `.CPYCBL`	Extract the source code from the AS400 libraries. The QCPYSRC library can contain copies for RPG, CL and COBOL programs.
DataStage	`.dsx` export of the jobs; `.dsx` exports of the stage types.

Cobol (not IBM)

Covers: Microfocus Cobol, GCOS Cobol, Cobol VMS.

Show file requirements

Technology	Requirement	Comment
Microfocus Cobol	All files used to build the system. Exact file types to be confirmed.	Please consult your CAST technical contact.
GCOS Cobol	All files used to build the system. Exact file types to be confirmed.	Please consult your CAST technical contact.
Cobol VMS	All files used to build the system. Exact file types to be confirmed.	Please consult your CAST technical contact.

SAP

Covers: SAP ABAP, SAP UI5 (Fiori), SAP Hybris, SAP BusinessObjects.

Show file requirements

Technology	Requirement	Comment
SAP ABAP	SAP ABAP extracted using the CAST SAP Extractor NG.	The CAST ABAP extractor extracts the ABAP source code, the database structure (tables, indexes, keys, …) and can also grab the table sizes. Various extraction options exist: per package, per date, per Transport Request, …
SAP UI5 (Fiori)	Same requirements as for web / HTML5 / jQuery technologies.
SAP Hybris	Same requirements as for Java/JEE technologies.
SAP BusinessObjects (Reporting Enterprise Solutions)	DMT’s Business Objects option must be used for source code extraction. DMT requires the location of the Business Objects Universes (`.unv` files) for extraction.

Scripting Languages

Covers: Korn shell, Bourne shell, C shell.

Show file requirements

Requirement	Comment
Each file must contain only a single artefact or component.

SQL — Database

Covers: T-SQL (Sybase and Microsoft SQL Server), Informix, MariaDB, MySQL, PostgreSQL, Oracle Server PL/SQL, SQLite, Teradata, IBM DB2.

For general documentation, see https://doc.castsoftware.com/technologies/sql/technos/.

For all the databases below, provide one DDL script per database/schema, including constraints (PK, FK), indexes, stored procedures, triggers, etc. The same DDL extraction examples apply, the schemas are analyzed using the SQL analyzer, and — where relevant — the sqltablesize file should be generated as described in XXL and XXS tables rules enablement.

Notes:

Incremental schema creation is not supported; incremental scripts should be removed from the delivered code.
Data creation/initialization must not be included in the script.

Show database-specific requirements

Database	Database-specific requirement
T-SQL (Sybase and Microsoft SQL Server)	The SQL Server / Sybase user used for extraction must have the privileges specified in the Microsoft SQL Server / Sybase ASE sections of Required RDBMS rights for packaging a database.
Informix
MariaDB
MySQL
PostgreSQL
Oracle Server PL/SQL	The Oracle user used for extraction must be `SYSTEM` or a dedicated extraction user with the privileges specified in the Oracle Server / Extraction user section of Required RDBMS rights for packaging a database.
SQLite
Teradata	Sample script based on the BTEQ query tool: Script. It needs the Teradata DB host name, user name, password and the DB names used by the application.
IBM DB2

NoSQL

Covers: MongoDB, Couchbase, MarkLogic, CouchDB, AzureCosmosDB, DynamoDB, Elasticsearch, Memcached, Redis.

NoSQL databases are accessed through frameworks written in the application’s own language, so there are no file types specific to the database itself. Deliver the application source code as described in the relevant language section (Java, .NET, Node.js, …).

Show database-specific requirements

Database	Access
MongoDB	Accessed from the application language’s files: JEE → Java files, .NET → .NET files, Node.js → JavaScript files.
Couchbase	JEE → Java files.
MarkLogic	Node.js → JavaScript files.
CouchDB	Node.js → JavaScript files.
AzureCosmosDB (Java, .NET)
DynamoDB (Java, .NET)
Elasticsearch (Java, .NET)
Memcached (Java, .NET)
Redis (Java, .NET)

Misc. Enterprise Solutions

Covers: TIBCO, SAP Power Builder, Oracle BPEL.

Show file requirements

Technology	Requirement	Comment
TIBCO	Project configuration files: `.aeschema`, `.sharedjdbc`, `.javaschema`, `.sharedhttp`, `.sharedjmscon`, `.process`, `.wsdl`, `.sharedjmsapp`. All Java source files of the application. All properties and XML files. The folder structure must be one sub-folder per project.	Typically all these files are under the same root folder.
SAP Power Builder	All the source code must be encoded in ASCII or a supported Unicode encoding (e.g. UTF-8).	Supported encoding/character sets are listed in Supported Character Sets.
SAP Power Builder	PowerBuilder Libraries (`.pbl`).	All PowerBuilder libraries from the application (and the framework, if any).
SAP Power Builder	If PowerBuilder is earlier than version 8: file `pb.ini`. If PowerBuilder is version 8 or later: files `xxx.pbw` and `xxx.pbt`.	`pb.ini` contains the starting PBL and the application’s name. `.pbw` is the PowerBuilder Workspace; `.pbt` is the PowerBuilder Target.
Oracle BPEL	Source files: `.bpel`, `.wsdl`, `.java`.	`.bpel` contains the steps/activities of the business process; `.wsdl` defines the web services orchestrated by the BPEL file; `.java` implements the web services defined in the WSDL.

Web

Covers: Angular, Angular.JS, JavaScript, jQuery, ReactJS, TypeScript, VBScript.

Show file requirements

Technology	Requirement	Comment
Angular.JS	All application and configuration files. Code before compilation (otherwise there will be generated code in the delivery). All source files including project and configuration files, e.g.: `.js` — source files `.properties`, `.config`, `.json`, `.yml` — properties and configuration files `.html` files `.css`, `.scss` files images, icons, etc. All libraries required to build the application, except external libraries that are not included in the analysis.	`.yaml`, `.js`, `.jsx`, `.css`, `.ts`, `.tsx`, `.json`, `.html`…
Angular	Source code before compilation. Extensions: `.ts`, `.html`, `.css` or `.scss`. The source folder containing `index.html`, `main.ts` and the `app` folder, plus the `app.modules.ts` file. `spec.ts` files are useless — don’t deliver them.	Source code written by developers is mandatory. If there is another specific file extension, it must be clarified by the customer.
JavaScript	All application and configuration files.	`.yaml`, `.js`, `.jsx`, `.css`, `.ts`, `.tsx`, `.json`, `.html`…
jQuery	The jQuery file, not the minified file. State the jQuery version used.	`.yaml`, `.js`
ReactJS	Source code before compilation. Extension: `.js` only. `.spec.js`, `.test.js`, `-spec.js` and `-test.js` files are useless — don’t deliver them.	Source code written by developers is mandatory. If there is another specific file extension, it must be clarified by the customer.
TypeScript	All application and configuration files.	`.yaml`, `.js`, `.jsx`, `.css`, `.ts`, `.tsx`, `.json`, `.html`…
VBScript	All application and configuration files.	`.vbs`

Node.js

Show file requirements

Requirement	Comment
All the source files of the application, including project and configuration files, for example: `.js`, `.jsx`, `.ts`, `.tsx` — source files `.pug`, `.jade`, `.vue`, etc. — files used by frameworks `.properties`, `.config`, `.json`, `.yml` — properties and configuration files `.html` files `.css`, `.scss`, `.sass` files images, icons, etc.	All the source code must be encoded in ASCII or a supported Unicode encoding (UTF-8, …).
Project files: `package.json`, `package-lock.json`.

Note: do not provide a copy of the node_modules/ directory.

To go further

This page details the source-code file types required per technology. This document is used by the CAST Administrator during the Qualification and Source Code Delivery phases, as detailed in Prepare and deliver the source code.