DRAFT - Attachment 02 - Exhibit A - NII - POV - ICD - VENDOR.pdf

Non-Intrusive Inspection (NII) Interface Control Document (ICD) January 28, 2025 i

Non-Intrusive Inspection (NII) Interface Control Document (ICD)

NII POV ICD

Version 5.9

Land Border Integration (LBI)

Non-Intrusive Inspection (NII) Interface Control Document (ICD) January 28, 2025 ii

Foreword

The Department of Homeland Security (DHS) has developed a System Engineering Life Cycle (SELC) that mandates a series of gate reviews during which the design of the system being developed is to be reviewed and approved. Each of these reviews becomes more detailed and is based on progressively more detailed design information that becomes available as the system progresses through the SELC Stages.

This document provides the templates to be used for documenting the design and supporting the design reviews that are part of the gate review process. Further, since CBP has decided to move from monolithic systems to systems built as a collection services and portlets, the system design documentation and design reviews / gate reviews must also change to reflect the migration to services. This document provides the basis for documenting the Service-Oriented Architecture (SOA)-based design of the system.

Questions relating to this document may be addressed to the

Approval/Owner’s Name:

Signature:

Non-Intrusive Inspection (NII) Interface Control Document (ICD) January 28, 2025

Document Revision History Amendment Record:

Issue Date Author Comments Version 1 04/01/2020 Initial Version 2 07/23/2020 Update input/output messages schema Version 3 10/28/2020 Update Carview/CertScan payload message schema

Update NII UI input/output message schema Version 3.1 01/26/2021 Update for Mexican State Codes MM Version 4 02/09/2021 Update vendor message Version 4 02/11/2021 Made grammar/syntax/formatting edits and added a table for acronyms & definitions Version 4 05/11/2021 Laura

Schneider Added CBP template

Version 5 07/29/2021 Laura Schneider

Added FLPR IB POV updates

Version 5.1 06/27/2023 Mikhail Maksimenko

Corrected site code and port code names in the vendor payload

Version 5.2 08/28/2023 Mikhail Maksimenko

Updated vendor license plate type definition to be “Type”.

Version 5.3 11/2/2023 Mikhail Maksimenko

Added API Key requirement and the NII API SSL certificate installation instructions

Version 5.4 12/5/2023 Mikhail Maksimenko

Added NII API URLs and DNS information, provided by EIOD team

Version 5.5 1/31/2024 Mikhail Maksimenko

Updated the NII API URLs and DNS information for EKS Kubernetes cluster

Version 5.6 2/6/2024 Mikhail Maksimenko

Updated the diagram

Version 5.7 6/13/2024 Mikhail Maksimenko

Updated the NII API endpoints, added Health Check and Vendor Payload

Version 5.8 01/28/2025 Brian Spangler

Adding a formal ‘heartbeat’ API endpoint.

Version 5.9 02/20/2025 Suzanne Nichols

Added Bulk dismissal and Operational status

The latest version of this document supersedes all other previous issues.

Distribution Record:

Issue Date Recipients

Contents

1. Terms and Acronyms

2. Overview

3. Process

4. Message Communications

4.1. HTTP Response Codes

4.2. Protocol and Transfer Method

4.3. Security Specifications

4.4. Data Format

4.5. Exceptions and Error Handling

5. Interface Definitions

5.1. X-ray inspection system - LBI NII App Server

Interface Specification Authentication Data Flow Message Schema

5.2. Vendor JSON Message Template

Suspect JSON message Non Suspect JSON Message

5.3. NII API URLs

5.4. DNS Information

5.5. Certificate Authority Installation Guide

1. Terms and Acronyms Term Definition DHS Department of Homeland Security CBP Customs and Border Protection LBI Land Border Integration NII Non-Intrusive Inspection ICD Interface Control Document RFID Radio Frequency Identification LPR License Plate Reader LSC Lane Security Controller LED Light Emitting Diode HTTP Hyper Text Transfer Protocol HTTPS Hyper Text Transfer Protocol Secure JSON JavaScript Objection Notification CICS Customer Information Control System(s) PPZ Pre-Primary Zone JPEG Joint Photographic Experts Group PNG Portable Network Graphics GIF Graphics Interchange Format TIFF Tag Image File Format IB In Bound POV Personal Owned Vehicle ROI Region of Interest POE Port of Entry MM Mexican State Codes FOUO For Official Use Only FCU Flex Control Unit

2. Overview This document describes the interface between the LBI NII LSC Unit (LCU), Flex Control Unit (FCU), LBI Server, and X-ray inspection system for the purposes of displaying Adjudication results and Lane data to the Booth Officers and Booth Officers acknowledge the Adjudication results.

Lane data includes License Plate Recognition (LPR), Face, Vehicle, and RFID data. Adjudication results include inspection level, inspection decision and comments.

3. Process Data collection and distribution begins with a vehicle processed in the X-ray inspection lane, and the X-ray inspection app sends the Adjudication results and LPR data to the LBI Endpoint. The vehicle continues through the primary lane where data is collected and packaged by the LSC and FCU via the Operations Service. As it is collected, the data is sent to an LBI endpoint.

Scenario of data collection and iterative message sends:

o Vehicle exits NII (X-Ray) inspection lane, an https POST message sends adjudication results and LPR data to the LBI endpoint.

o Vehicle enters primary lane, triggering RFID reads, initiating LED Counter to 0.

For each RFID read, the Operations service sends LBI endpoint an

“LSC/FCU RFID” message and updates the LED Counter.

o Vehicle continues driving through in primary lane, triggering sensor signals, Front

LPR camera, and Occupant camera.

On receive of data from front LPR camera, the Operations service sends full LPR source image and plate patch images, as well as OCR data & state and country codes to the LBI endpoint in an “LSC/FCU LPR” message.

On receive of data from the Occupant camera, the Operations service sends source image and all face patch images to the LBI endpoint in an “LSC/FCU Face” message.

o Vehicle exits primary lane, triggering Rear LPR and ending RFID reads.

On receive of data from rear LPR camera, Operations service sends full

LPR source image and plate patch images, as well as OCR data to LBI endpoint in a second “LSC/FCU LPR” message.

RFID reads are discontinued, and LED Counter is reset.

o In addition to vehicle adjudication results, a periodic heartbeat is provided by the vendor. The message is posted to the LBI NII Heartbeat endpoint provided below.

o In the event of a bulk dismissal messages will be sent to the LBI endpoint with a

“Not Adjudicated” in the “InspectResult” field.

4. Message Communications Message communications from the X-ray inspection lane to the LBI endpoint is send-only.

Communicating data via HTTP is accomplished using RESTful web services, exercising uses of POST request methods, and the LBI NII API accepting collected data enclosed in the body of the request.

4.1. HTTP Response Codes

Following HTTP protocol, Operations service expects the following category of response codes:

• 1xx: Informational

• 2xx: Success

• 3xx: Redirection

• 4xx: Client Error

• 5xx: Server Error

For 5xx Server Error, additional details may be established in advance since these are errors returned by the LBI web service and generally in connection to an issue with the posted message data.

Any custom 5xx error is to be included in this document.

LBI Server

HTTP

Response

LEP Vendor Server

HTTP

Request

4.2. Protocol and Transfer Method

Messages are exchanged over HTTPS via RESTful API. In HTTPS, the communication protocol is encrypted using TLS.

Messages are expected to be queued by LBI with LSC/FCU operating in a collect and send manner. As part of the HTTP protocol, the only REST response is an HTTP code such as 200 for success, 5XX type to indicate messaging error or 4XX to identify a protocol issue.

4.3. Security Specifications

Messages conforms to the HTTP protocol with expectation of current TLS support levels as established by CBP security compliance requirements.

4.4. Data Format

JSON message structure will adhere to templates defined in this document. Field names, their definitions, etc. are not expected to change unless formally proposed, reviewed, and agreed updates applied to the

ICD.

Spacing and Case styling remain undetermined. As of ver. 001 of the ICD, spaces (no tabs) are used for purposes of indentation and overall document structure. Camel Case, or camel caps, is the current format for styling fields, but can change if necessary.

**A dependency on standardizing field name case is in the testing of messaging and LBI endpoint processing. Once the dependency is resolved, this section of the ICD will be updated.**

4.5. Exceptions and Error Handling

All exceptions or errors occur during the messages exchange will be logged in the NII error logs.

4.6. Frequency of Communications

Heartbeat messages will be send every 5 minutes totaling 12 messages an hour.

5. Interface Definitions

5.1. X-ray inspection system - LBI NII App Server

Interface Specification Adjudication message containing inspection results from X-ray inspection data sent to LBI NII App Server. Command center officer will send one combined json message including RFIDs (multiple), Images (Front LPR, Rear LPR and Scene), License Plate Information (Front, Rear) and Adjudication Result to LBI NII interface.

Authentication Each HTTP request will need to set API key in HTTP header before send, Header name: X-API-KEY (case insensitive) Header value: <LBI NII provided value> The complete HTTP header will look like this:

Data Flow

Message Schema

"payload": "{Escaped JSON String}”, //payload data in escaped JSON format}

Heartbeat message

• Message Type: {“Heartbeat Message:}

"version": "{STRING}", // Vendor name - Message Schema Version 4.0 "port_code":"{STRING4}", // Port of Entry (POE). i.e. 2309/Donna, 2305/Anzal "site_code":"{STRING4}", // The site within the POE i.e. L23T/Donna, L23X/Anzal "vendor": "{STRING}", // Vendor name "description": "{STRING}", // Vendor description "createDateTime": "{STRING}", // Timestamp e.g. 2020-06-18T10:45:05.2248877-04:00 "transactionID": "{STRING}" // Unique string to identify the message e.g. UUID

Operational status message

• Message Type: {“Operational Status Message:}

• Status types include machine on/off/repair

"version": "{STRING}", // Vendor name - Message Schema Version 4.0

"port_code":"{STRING4}", // Port of Entry (POE). i.e. 2309/Donna, 2305/Anzal

"site_code":"{STRING4}", // The site within the POE i.e. L23T/Donna, L23X/Anzal

"vendor": "{STRING}", // Vendor name

"description": "{STRING}", // Vendor name - Non-Intrusive Inspection (NII)

"status": "{STRING}", // NII machine status

"createDateTime": "{STRING}", // Timestamp e.g. 2020-06-18T10:45:05.2248877-04:00

"transactionID": "{STRING}" // Unique string to identify the message e.g. UUID

LEP Vendor Server LBI NII App

HTTP

Payload message (input)

• Message Type: {“Adjudication Message”}

• Plate Type: {“Front”, “Rear”}

• Image Type: {“FrontLPR”, “RearLPR”, “Scene”}

• Inspection Level: {Free text, pass inspection level}

• Inspection Result: {“Non Suspect”, “Suspect”}

• Country Code: 2 letter abbreviation (ISO 3166-1)

• State Code: 2 letter abbreviation (US and CA, ISO 3166, MM for all Mexican states)

"version": "{STRING}", // Vendor name - Message Schema Version 4.0 "port_code":"{STRING4}", // Port of Entry (POE). i.e. 2309/Donna, 2305/Anzal "site_code":"{STRING4}", // The site within the POE i.e. L23T/Donna, L23X/Anzal "vendor": "{STRING}", // Vendor name - Site name, e.g. Leidos-OTLF "description": "{STRING}", // Vendor name - Non-Intrusive Inspection (NII) "messageId": "{STRING}", // Reserved "createDateTime": "{STRING}", // Timestamp e.g. 2020-06-18T10:45:05.2248877-04:00 "messageType": "{STRING}", // Adjudication Message "transactionID": "{STRING}" // Unique string to identify the message e.g. UUID

"licensePlateInfo": [ "plateNumber": "{STRING}", // License plate number Ex. ABCD123 "Type": "{STRING}", // Front or Rear "state": "{STRING}", // 2 letter state code for US and Canada, MM for Mexico "country": "{STRING}" // 2 letter country code Ex. US, CA, MX … // Additional license plates

"RFID": [

"userData": "{STRING}", // RFID "tid": "{STRING}", // Transponder ID or “” "epcData": "{STRING}", // Electronic product code or “” "antenna": "{NUMBER}", // Antenna number, e.g., 1 "readTime": "{STRING}", // Timestamp, e.g., 2020-06-18T10:45:05.2248877-04:00 "versionNo": "{STRING}" // Version, e.g., 2.0 … // Additional RFIDs

"images": [{ "imageData": "{STRING}", // Base64 image string "imageType": "{STRING}" // Image type “FrontLPR”, “RearLPR” or “Scene” … // Additional images

"InspectionResults": [ "Comments": "{STRING}", // Free text e.g. Open trunk "ImageAnalyst": "{STRING}", // Name or id of analyst e.g. 12345678 "InspectionLevel": "{STRING}", // Free text "InspectResult": "{STRING}", // Inspection result. “Suspect”, “Non Suspect”, or “Not Adjudicated” (Which would be the case for bulk dismissal)

5.2. Vendor JSON Message Template

Suspect JSON message

Non Suspect JSON Message

5.3. NII API URLs (EKS Kubernetes Cluster)

Base URLs

SAT (lower) environment: https://nii-pov-api.sat.mesh.cbp.dhs.gov Production environment: https://nii-pov-api.prod.mesh.cbp.dhs.gov

These are not endpoints, the vendor payloads should not be sent here.

Health Check Endpoints SAT (lower) environment: https://nii-pov-api.sat.mesh.cbp.dhs.gov/health Production environment: https://nii-pov-api.prod.mesh.cbp.dhs.gov/health

These endpoints can be used to check connectivity and verify the API is up and running. They can be accessed from a browser, from the same local subnet where the vendor application resides. The response would look like this:

Heartbeat Endpoints SAT (lower) environment: https://nii-pov-api.sat.mesh.cbp.dhs.gov/Heartbeat Production environment: https://nii-pov-api.prod.mesh.cbp.dhs.gov/Heartbeat

These endpoints are used to provide LBI with a site’s NII command center online status, the heartbeat indicating the network path is clear to post and receive data. The response is an HTTP 200 status code.

Vendor Payload Endpoints SAT (lower) environment: https://nii-pov-api.sat.mesh.cbp.dhs.gov/api/VendorPayload Production environment: https://nii-pov-api.prod.mesh.cbp.dhs.gov/api/VendorPayload

These endpoints should be used to send vendor payloads.

https://nii-pov-api.sat.mesh.cbp.dhs.gov/ https://nii-pov-api.prod.mesh.cbp.dhs.gov/ https://nii-pov-api.sat.mesh.cbp.dhs.gov/health https://nii-pov-api.prod.mesh.cbp.dhs.gov/health https://nii-pov-api.sat.mesh.cbp.dhs.gov/Heartbeat https://nii-pov-api.prod.mesh.cbp.dhs.gov/Heartbeat https://nii-pov-api.sat.mesh.cbp.dhs.gov/api/VendorPayload https://nii-pov-api.prod.mesh.cbp.dhs.gov/api/VendorPayload

5.4. DNS Information (EKS Kubernetes Cluster)

Note: this information was provided by EIOD team, for questions please contact Kiamars Jafari at kiamars.jafari@cbp.dhs.gov

SAT (lower) environment:

CNAME = nii-pov-api.sat.mesh.cbp.dhs.gov Addresses: 10.188.89.44 10.188.90.27 10.188.89.212 AWS hostname = k8s-istioing-istioing-24d041dee5-fded0cf641d3d611.elb.us-east-1.amazonaws.com

Production environment:

CNAME = nii-pov-api.prod.mesh.cbp.dhs.gov Addresses: 10.156.210.53 10.156.208.38 10.156.209.34 10.156.208.246 10.156.209.141 AWS hostname = k8s-istioing-istioing-eb67e6039f-f6352adf2deaecfe.elb.us-east-1.amazonaws.com

Google DNS servers:

8.8.8.8 8.8.4.4

5.5. Certificate Authority Installation Guide

CBP is using CBP generated certificates for internal and external web applications between client and server authentication.

LBI NII team will provide vendor with the CBP certificate chain along with the new CBP certificate issued for LBI NII Web API. Vendor will need to include the CBP certificate chain in their server’s trust store.

Installation Guide:

1. Open certificate file, mailto:kiamars.jafari@cbp.dhs.gov

2. Click “Install Certificate…”

3. Select to install on “Local Machine”.

4. Choose to place certificate in “Trusted Root Certification Authorities”

5. Follow the screen workflow to finish the installation.

6. Repeat step 1-5 for other certificates.

7. To validate the certificate is installed successfully, open URL LBI NII provided in any web browser in vendor’s server machine, the lock icon ( ) should be next to URL in the address bar.