docs: Authorization Report

docs/authorization-report/AcronymGuide.md

@@ -0,0 +1,47 @@
+
+# Authorization Report Acronym Guide
+
+Acronym | Meaning | Context
+-- | -- | -- 
+AAA | HEC AAA Client (authentication/authorization client) | Java client used to interface with CWMS authentication; see https://mvnrepository.com/artifact/mil.army.usace.hec/cwms-aaa-client
+ABAC | Attribute-Based Access Control | a paradigm implemented in Database systems to finely control access to tables and data via the attributes of the data.
+AIS | Army Information System | general term for any Army IT solution
+ANSI | American National Standards Institute | A non-profit organization that develops standards used in IT and other products world-wide.
+API | Application Program Interface | An interface at an online resource for other systems to connect to in order to share data
+AWS | Amazon Web Services | Amazon's cloud-based computing solution
+CAC | Common Access Card | Smart cards used by the DoD and other agencies to authorize persons into IT hardware and software solutions.
+CDA | CWMS Data API | API façade (Javalin) used by clients/services to access CWMS DB; also the name of the main GitHub repo
+CI/CD | Continuous Integration / Continuous Delivery (or Deployment) | DevSecOps pipeline practice used for automated build, test, and release
+COTS | Commercial Off-The Shelf | a term for commercially developed software available for purchase to solve a need, as opposed to a home-grown or internally developed solution
+CRUD | Create, Read, Update, and Delete | The four main operations that can be performed on a row of data within a database, and used to define access permissions.
+CWMS | Corps Water Management System | Automated information system used to manage USACE's mission. See https://www.hec.usace.army.mil/cwms/
+DBA | Database Administrators | Database management professionals who have super-user access a database and whose job it is to maintain all aspects of the database system and the data contained therein.
+DoD | Department of Defense | The Department of Defense, underneath which the Department of the Army sits in the Executive Branch of the government.
+ELK | Elasticsearch, Logstash, Kibana | Common logging/observability stack used for metrics and trace analysis
+HEC | Hydrologic Engineering Center | HEC provides support to USACE's overall water management mission.  See https://www.hec.usace.army.mil/about/MissionStatement.aspx
+HMS | Hydrologic Modeling System | An HEC product for hydrologic modeling; see https://www.hec.usace.army.mil/software/hec-hms/
+HTTP | Hypertext Transfer Protocol | the TCP/IP stack protocol that is the basis for the modern internet, enabling hyper linking between web sites.  See https://en.wikipedia.org/wiki/HTTP
+IT | Information Technology | a general term for systems and solutions built in and around computing platforms.
+IWR | Institute for Water Resources | Overall organization supervising the work of CWMS
+JSON | JavaScript Object Notation | an Open source file format/data interchange format that has become a defacto standard for sending data in the modern era.  See https://en.wikipedia.org/wiki/JSON
+JWT | JSON Web Token | A method for providing authentication and encryption in JSON packages.  See https://en.wikipedia.org/wiki/JSON_Web_Token
+NOAA | National Oceanic and Atmospheric Administration | External agency that utilizes this dataset.  See https://www.noaa.gov/
+OIDC | OpenID Connect | An open source authentication protocol that enables users to be authenticated by 3rd party sites.  See https://en.wikipedia.org/wiki/OpenID
+OPA | Open Policy Agent | An open-source policy engine that streamlines policy implementations for organizations.  see https://www.openpolicyagent.org/
+PWS | Performance Work Statement | Government terminology for the document that defines a solution to which the government seeks a contracting proposal from private companies to pay to solve.
+QA | Quality Assurance | Within the context of a data-centric system, Quality Assurance are analysis activities performed on data to ensure the cleanliness and accurateness of data before adding it to the larger dataset.
+Q-38 | RFC Question #38 | Q-38 was an important question raised during the pre-award solicitation Q&A process where USACE staff answered the question, ' What are the specific limitations of the current Role-Based Access Control that the new authorization model needs to address?"  The government's response helped define the solutioning found in this report.
+PL/SQL | Procedural Language/Structured Query Language | This is Oracle's proprietary implementation of ANSI-standard SQL, which extends the standard to perform operations that are only supported in Oracle RDBMS solutions.
+RAS | River Analysis System | An HEC-developed flow-analysis system.  See https://www.hec.usace.army.mil/software/hec-ras/
+RBAC | Role-Based Access Control | a paradigm implemented in Database systems to control access to tables and data via the use of roles and users assigned to those roles
+RDS | Relational Database Service | Amazon Web Service's managed database subsystem
+REST | Representational State Transfer | An architectural guideline used to develop internet-based solutions.  See https://en.wikipedia.org/wiki/REST
+RDBMS | Relational Database Management System | A system used to store data in a relational manner.  These are 3rd party/COTS enterprise products usually well known within the IT industry.
+RLS | Row-Level Security | PostgreSQL feature for row-based access control; target future-state equivalent of Oracle VPD
+SCADA | Supervisory Control and Data Acquisition | A computerized system that monitors and controls industrial processes.  In the case of HEC, these solutions typically refer to Automated Collection Systems such as water level monitors and other automated systems that feed data into the database.
+SQL | Structured Query Language | An ANSI-defined standard methodology for working with data stored within an RDBMS platform.
+TLS | Transport Layer Security | Cryptographic protocol securing API/OPA traffic (HTTPS)
+UI | User Interface | The method by which users interact with a computer system.
+USGS | United States Geological Survey | External federal agency that partners with USACE to provide data.  See https://www.usgs.gov/
+VPD | Virtual Private Database | The Oracle feature that controls the security in the current solution.
+USACE | United States Army Corps of Engineers | Charged with providing Engineering solutions to the Army.  see https://www.usace.army.mil/

docs/authorization-report/Api-Overview.rst

@@ -0,0 +1,112 @@
+TimeSeries API Discussion Table (with Examples & Issues)
+=========================================================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 25 25 30
+
+   * - Endpoint (Swagger Link)
+     - Highlights from Discussion
+     - Tests / Recommendations & Issues
+     - Example Calls
+   * - `GET /timeseries <https://cwms-data.usace.army.mil/cwms-data/swagger-ui.html#/TimeSeries/getTimeseries>`__
+     - - Core endpoint, most used in CDA.
+       - **Office is required** even though docs once showed optional.
+       - Defaults: 24h window, 500 records per page.
+       - Supports ``unit-system`` (EN/SI), ``datum``, ``version-date``.
+       - Supports ``include-entry-date``.
+       - ``trim=true`` removes leading/trailing nulls.
+       - ``regular`` vs ``pseudo-irregular`` series behavior explained.
+     - - Always specify ``office``.
+       - Use ``America/Chicago`` instead of ``US/Central``.
+       - **Time Zone Issue**: Defaults to UTC if not specified.
+       - **Trim + Page-size Edge Case**: Some values disappeared unless page-size adjusted.
+       - Raise ``page-size`` or parallelize by date slices for large pulls.
+       - For CSV downloads in browsers: prefer ``format=csv`` query (**Format vs Accept Header Conflict**).
+     - **curl**::
+
+          curl "https://cwms-data.usace.army.mil/cwms-data/timeseries?name=KEYS.ELEV.Inst.1Hour.0.CCP-RAW&office=SWT&begin=2025-08-01T00:00:00Z&end=2025-08-07T00:00:00Z&unit-system=EN&timezone=America/Chicago&page-size=2000&format=csv" -o data.csv
+
+       **Python (requests)**::
+
+          import requests
+          r = requests.get("https://cwms-data.usace.army.mil/cwms-data/timeseries",
+                           params={
+                               "name": "KEYS.ELEV.Inst.1Hour.0.CCP-RAW",
+                               "office": "SWT",
+                               "begin": "2025-08-01T00:00:00Z",
+                               "end": "2025-08-07T00:00:00Z",
+                               "unit-system": "EN",
+                               "timezone": "America/Chicago",
+                               "page-size": 2000
+                           },
+                           headers={"Accept": "application/json"})
+          print(r.json())
+   * - `GET /timeseries/recent <https://cwms-data.usace.army.mil/cwms-data/swagger-ui.html#/TimeSeries/getRecentTimeseries>`__
+     - - Used for dashboards, gets most recent values.
+       - Accepts ``ts-ids`` (comma separated), ``group-id``, or ``category-id``.
+       - Performance fixes (latest ~300ms).
+     - - Use comma-separated ``ts-ids``.
+       - **Group/Category Issue**: returned empty in tests → likely bug.
+       - Watch URI length (~2000 chars); chunk large sets.
+     - **curl**::
+
+          curl "https://cwms-data.usace.army.mil/cwms-data/timeseries/recent?office=SWT&ts-ids=KEYS.ELEV.Inst.1Hour.0.CCP-RAW,KEYS.FLOW.Inst.1Hour.0.CCP-RAW"
+
+       **Python**::
+
+          r = requests.get("https://cwms-data.usace.army.mil/cwms-data/timeseries/recent",
+                           params={
+                               "office": "SWT",
+                               "ts-ids": "KEYS.ELEV.Inst.1Hour.0.CCP-RAW,KEYS.FLOW.Inst.1Hour.0.CCP-RAW"
+                           })
+          print(r.json())
+   * - `GET /timeseries/filtered <https://cwms-data.usace.army.mil/cwms-data/swagger-ui.html#/TimeSeries/getFilteredTimeseries>`__
+     - - SQL-like queries (``greater than``, ``less than``, etc.).
+       - Session noted powerful but time-consuming.
+     - - Use only when filtering by values is essential.
+       - Test carefully on large ranges; may impact performance.
+     - **curl**::
+
+          curl "https://cwms-data.usace.army.mil/cwms-data/timeseries/filtered?office=SWT&name=KEYS.ELEV.Inst.1Hour.0.CCP-RAW&where=value>500"
+
+       **Python**::
+
+          r = requests.get("https://cwms-data.usace.army.mil/cwms-data/timeseries/filtered",
+                           params={
+                               "office": "SWT",
+                               "name": "KEYS.ELEV.Inst.1Hour.0.CCP-RAW",
+                               "where": "value>500"
+                           })
+          print(r.json())
+   * - `GET /timeseries/profiles <https://cwms-data.usace.army.mil/cwms-data/swagger-ui.html#/TimeSeries/getTimeseriesProfiles>`__
+     - - 2D profiles (e.g., values by depth).
+       - Session confirmed little/no data on national instance.
+     - - Verify your district has data before building UI.
+       - May be optional feature.
+     - **curl**::
+
+          curl "https://cwms-data.usace.army.mil/cwms-data/timeseries/profiles?office=SWT&name=PROFILE.DEPTH.1Day.0.WQ"
+
+       **Python**::
+
+          r = requests.get("https://cwms-data.usace.army.mil/cwms-data/timeseries/profiles",
+                           params={
+                               "office": "SWT",
+                               "name": "PROFILE.DEPTH.1Day.0.WQ"
+                           })
+          print(r.json())
+   * - `GET /catalog/timeseries <https://cwms-data.usace.army.mil/cwms-data/swagger-ui.html#/Catalog/getTimeseriesCatalog>`__
+     - - Lists available time series, units, intervals, time zones.
+       - Essential for validation.
+     - - Query before building dashboards to ensure valid IDs.
+       - Use to distinguish ``regular`` vs ``pseudo-irregular`` (tilde in ID).
+     - **curl**::
+
+          curl "https://cwms-data.usace.army.mil/cwms-data/catalog/timeseries?office=SWT"
+
+       **Python**::
+
+          r = requests.get("https://cwms-data.usace.army.mil/cwms-data/catalog/timeseries",
+                           params={"office": "SWT"})
+          print(r.json())

docs/authorization-report/README.md

@@ -0,0 +1,36 @@
+
+# USACE CWMS Authorization Methods Report
+
+This report provides a comprehensive analysis and set of recommendations for modernizing the authorization methods used in the U.S. Army Corps of Engineers (USACE) Corps Water Management System (CWMS). The report is structured as a multi-section document, with each file representing a distinct chapter or analysis area.
+
+The primary goal is to evaluate the current Oracle Virtual Private Database (VPD) approach, document its limitations, and propose a future-ready authorization architecture that meets the requirements outlined in the Performance Work Statement (PWS) and stakeholder interviews. The report covers:
+
+- An inventory and analysis of the current CWMS Data API and its security model
+- Detailed use cases for all user personas, including operational staff, automated systems, and external partners
+- A gap analysis of CRUD permissions and policy requirements for each persona
+- Comparative evaluation of candidate policy models, including OPA-based and traditional RBAC/ABAC approaches
+- Security and performance analysis aligned with NIST RMF standards
+- A final comparative analysis and recommendation for adopting a policy-as-code approach using Open Policy Agent (OPA)
+ - An implementation and UI plan outlining delivery options and admin tooling
+ - An acronym guide centralizing terminology used across sections
+
+The report is intended for technical stakeholders, system architects, and decision-makers responsible for CWMS security and modernization. It provides both high-level strategy and detailed technical guidance to support a secure, flexible, and future-proof authorization framework for CWMS.
+
+---
+
+
+## Table of Contents
+
+- [Current Oracle VPD Architecture & Analysis](./RptSec1-VPD.md)
+- [Inventory & Analysis of CWMS-Data-API Code](./RptSec2-API.md)
+- [Gather Use-Cases & Dependencies](./RptSec3-UseCases.md)
+- [CRUD-Permission Gap Analysis](./RptSec4-CRUDGapAnalysis.md)
+- [Candidate Policy Model Alternatives](./RptSec5-PolicyCandidates.md)
+- [NIST RMF-Aligned Security & Performance Analysis](./RptSec6-NIST.md)
+- [Comparative Analysis & Recommendation](./RptSec7-ComparativeAnalysis.md)
+- [Implementation & UI Plan](./RptSec8-ImplementationAndUI.md)
+- [Acronym Guide](./AcronymGuide.md)
+
+---
+
+Each file in this repository represents a separate section of the report. Open the relevant file to view the corresponding content.