Third-party libraries
Last Updated:
Third-party libraries can provide valuable functionality when developing on VA.gov, but they come with potential risks, including compatibility, performance, and security concerns. With so many contributors across VA.gov, those risks are heightened and it is necessary to account for all external code that comes into the project. To mitigate these risks, the Platform has established a detailed process for evaluating and approving third-party libraries, ensuring that any new additions are thoroughly vetted and properly maintained.
What’s a third party library?
Third-party libraries can help us do lots of things when writing code. Sometimes it can solve a problem we didn’t know the solution to, while other times it can just be much more convenient than writing your own solution. However, for as many positives as third-party software can bring, there can also be negatives. When adding a third-party package to VA.gov, there are many things that need to be considered to decide if it’s a good choice.
One of the most critical considerations is the library’s compatibility with the existing codebase and dependencies. Ensuring that the library integrates smoothly without causing conflicts is essential. This includes checking the library’s version against those of other dependencies to avoid issues like version mismatches or deprecated features. Additionally, understanding the library’s purpose and whether it fits the specific needs of your project is crucial. Using a well-maintained, widely-used library can significantly reduce risks, as such libraries tend to have active communities that quickly address bugs and security vulnerabilities.
Another important factor is evaluating the performance impact of the library. Introducing a third-party library can add to the overall size of your project, potentially slowing down page load times and affecting user experience. It’s important to assess whether the benefits provided by the library justify any additional load it brings. Minimizing dependencies by choosing lightweight, efficient libraries can help maintain optimal performance. Additionally, you should consider the long-term maintenance and support for the library. A library that is actively maintained with regular updates is preferable, as it will likely remain secure and compatible with future web technologies. Before integrating a third-party library, always review its documentation, check for any reported issues, and conduct thorough testing to ensure it integrates well with your project.
Security concerns are also a significant consideration when integrating a third-party library into a web project. Even widely used libraries can introduce vulnerabilities, such as cross-site scripting (XSS), SQL injection, or other security flaws, especially if the library is outdated or poorly maintained. It’s essential to assess the library’s security reputation by reviewing its history of vulnerabilities and how quickly its maintainers address them. Additionally, consider the source of the library—prefer official repositories or trusted sources to minimize the risk of introducing malicious code. Using tools like vulnerability scanners can help detect potential security issues within the library. Regularly monitoring for updates and patches is also critical, as new vulnerabilities can emerge over time. By being vigilant about the security implications of third-party libraries, you can help protect VA.gov from potential attacks and data breaches.
Adding libraries
The process
The following steps outline the process that should be followed for package additions:
Before adding a package, ask the following questions:
How recently was the package updated? (should be recent)
Is the package still actively maintained? (should be)
Does the package have a large number of downloads? (Low download numbers can be indicative of a poor package).
Does the package currently have any, or has had a history of security vulnerabilities? (Security is paramount)
Is there another library on VA.gov that already does this function? (duplicating code becomes a drag on performance)
Has another team possibly written custom functionality to solve for the absence of this library, that can be shared instead of installed separately?
Is there another library that might be better suited for this purpose? One that’s more secure or better supported? One that’s more flexible?
If all of the items in step 1 have checked out, write up a proposal for the library you are wanting to add. This ideally would be done in a Slack Canvas, as all related parties may access those. This proposal should contain:
Background on the library.
What functionality it’s going to be assisting in performing.
Why it’s necessary as opposed to a lighter solution.
Documentation of research performed including the docs for the library, packages it was compared to, and why this solution was ultimately chosen.
Attend the practice area CoP meeting to present your idea for group discussion with the CoP and attendees:
Front End CoP Meetings are Thursday @ 2pm ET. Inquire in #platform-cop-frontend for an invitation. This group primarily handles Node Package additions and third-party GitHub actions.
Back End CoP meetings are Monday @ 12:15pm ET. Inquire in #platform-cop-backend for an invitation. This group primarily handles Ruby Gem additions.
Providing the CoP decides to move forward with the package, the next step would be the user reaching out to the Platform Security Team. The COP can assist with the introduction if necessary.
If this is process is being followed for a new Ruby gem, you’ll need Platform Security’s approval to move on to step 5. Contact them in #platform-security. Once this is complete, move on to step 5. Note: in the rare case that a gem is not open-source, carries a commercial license, or has installable components, you’ll need to do step b (the TRM process) instead.
The first thing we will want to do is check the new software against the TRM (you need to be connected to the VA network to access this link). If it's not there, the first step would be to check if there is another piece of software already in the TRM that can accomplish this task that we can use instead. If not, we'll submit for the new piece of software to be added. If it gets approved, then we're done and all we need to do is update Platform Security’s running list of what software packages we've used. If it gets denied, the requesting team will have to either appeal, work with security to put a POAM in place (with appropriate justifications), or come up with an alternate solution.
The last step would be the CoP running the software proposal by the Platform Engineering PO. It’s important to ensure that all other approvals have been met before this step. The PO may respond with some additional questions and will either approve the request, or request some adjustments. If the PO adamantly denies the request, the PO should reach out to the PO of the requesting team to discuss further steps.
At this point the CoP will regroup with the team member to inform them of the status of the request and any additional information that may be needed.
What happens after a package is added?
Once a package has been added, the team that requested it is primarily responsible for any customizations needed to make the library work the way they need it to (settings, etc.). The addition of the package should be communicated to the rest of the VFS teams by the team that is adding it, to ensure that everyone knows that software is now available for use (and especially to help duplicate libraries being added for the same purpose). Additionally, if it is a security-related concern, the CoP may implement checks in GitHub Actions or eslint to enforce the proper usage of this new package.
Upgrading libraries
If a library needs to be upgraded, the responsibility falls into one of two categories:
Global Dependencies - Global dependencies in vets-website or vets-api is the responsibility of Platform to keep updated.
App Dependencies - Local dependencies of an app, such as installed with yarn workspaces, is the responsibility of the app team to keep up to date.
If a library is not in the TRM–and should be–(see Step 4 of The process) when it is upgraded, it will need to go through approval by security via being added to the TRM. If it is not approved, the library may need to be replaced as to not present a security issue in our projects. The goal is to eventually have all software used on VA.gov cataloged in the TRM.
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.