Attachment 02_Exhibit A_NII_POV_ICD_VENDOR_v5.9.docx

NII POV ICD

Version 5.8

Land Border Integration (LBI)

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 ii System Design Document Template V1.0 (07/16/09)

Document Revision History Amendment Record:

Initial

Update input/output messages schema

Update Carview/CertScan payload message schema Update NII UI input/output message schema

Update for Mexican State Codes MM

Update vendor message

Made grammar/syntax/formatting edits and added a table for acronyms & definitions

Spangler Adding a formal ‘heartbeat’ API endpoint.

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

Distribution Record:

Contents

Terms and Acronyms

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.

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:

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

· 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.

· 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.

· 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.

· 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.

· In the event of a bulk dismissal messages shall be sent to the LBI endpoint with a “Not Adjudicated” in the “InspectResult” field.

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.

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.

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.

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

Data Format JSON message structure shall 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.** Exceptions and Error Handling All exceptions or errors occur during the messages exchange shall be logged in the NII error logs.

Frequency of Communications Heartbeat messages shall be sent every 5 minutes totaling 12 messages an hour.

Interface Definitions 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 s 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 shall look like this:

Data FlowHTTP Post

LEP Vendor Server LBI NII App Server

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

Heartbeat message

· Message Type: {“Heartbeat Message:}

1.1.1.1. Operational status message

· Message Type: {“Operational Status Message:}

· Status types include machine on/off/repair

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)

"licensePlateInfo": [

… // Additional license plates

"RFID": [

… // Additional RFIDs

"images": [{

… // Additional images

"InspectionResults": [

"InspectionLevel": "{STRING}", // Free text "InspectResult": "{STRING}", // Inspection result. “Suspect”, “Non Suspect”, or “Not Adjudicated” (Which would be the case for bulk dismissal) Vendor JSON Message Template Suspect JSON message

Non Suspect JSON Message

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.

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

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 shall need to include the CBP certificate chain in their server’s trust store.

Installation Guide:

1. Open certificate file,

1. Click “Install Certificate…”

1. Select to install on “Local Machine”.

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

1. Follow the screen workflow to finish the installation.

1. Repeat step 1-5 for other certificates.

1. 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.

LBI Server

HTTP

Response

LEP Vendor Server

HTTP

Request image1.png image2.png image3.png image4.png image5.png image6.png image7.png image8.png image9.png image10.png image11.png image12.png