Git Product home page Git Product logo

amzn / oss-attribution-builder Goto Github PK

View Code? Open in Web Editor NEW
79.0 9.0 27.0 3.31 MB

The OSS Attribution Builder is a website that helps teams create attribution documents (notices, "open source screens", credits, etc) commonly found in software products.

License: Apache License 2.0

HTML 0.12% TypeScript 97.78% JavaScript 1.60% Dockerfile 0.15% SCSS 0.34%
licensing open-source-tooling website

oss-attribution-builder's Introduction

OSS Attribution Builder

Build Status

OSS Attribution Builder is a website that helps teams create attribution documents for software products. An attribution document is a text file, web page, or screen in just about every software application that lists the software components used and their licenses. They're often in the About screens, and are sometimes labeled "Open Source Notices", "Credits", or other similar jargon.

Screenshot

Quickstart

  1. Install Docker
  2. Clone this repository
  3. Run docker-compose up
  4. Visit http://localhost:8000/
    • The demo uses HTTP basic auth. Enter any username and password. Use admin to test out admin functionality.

Using the Website

See documentation:

Caveats

The attribution builder was originally an Amazon-internal tool. Some portions had to be removed to make this a sensible open source project. As such, there are some warts:

  • Projects have contact lists, but at the moment the UI only supports one contact (the legal contact).

These will all be fixed in time, but be aware that some things might be weird for a while.

Custom deployment

If you're ready to integrate the attribution builder into your own environment, there are some things to set up:

Configuration

Open up config/default.js and poke around. This configuration launches when you run docker-compose or otherwise launch the application.

Licenses

The attribution builder has support for two types of license definitions:

  • SPDX identifiers
  • "Known" license texts and tags

SPDX identifiers are just used for pre-filling the license selector, but do not (currently) have texts. The more useful type of license is a "known" license, where you (the administrator) supply the text of the license and any tags you'd like to apply.

For information on adding your own "known" licenses, see the license README. There are two existing licenses in the same directory you can look at for examples.

Tags

Tags allow you to add arbitrary validation rules to a license. They can be useful for:

  • Verifying a license is being used in the right way (e.g., LGPL and how a package was linked)
  • Annotating a particular license as needing follow up, if your business has special processes
  • Providing guidance on attribution for licenses with many variants
  • Modifying the how a license is displayed in an attribution document

For information on what tags can do and how to create your own, see the tags README.

Extensions

The attribution builder offers some form of extensions that allow you to alter client-side site behavior and appearance, without needing to patch internals. This can make upgrades easier.

See the extensions README for details.

Authentication module

The attribution builder supports being able to restrict access to certain people or groups using project ACLs. These can also be used for administration and to "verify" packages (details on that in a later section). The default implementation nullauth is not very useful for most environments; you will want to write your own when launching more broadly.

See the base auth interface for implementation details.

Running

To start up the server, you should run build/server/localserver.js after building with npm run build. There are some environment variables you'll probably want to set when running:

  • NODE_ENV should most likely be set to production
  • CONFIG_NAME should be set to the basename (no extension) of your configuration file you created above. The default is "default".

The server runs in HTTP only. You probably want to put a thin HTTPS web server or proxy in front of it.

Contributing

See CONTRIBUTING for information.

Development

npm install and then npm run dev will get you off the ground for local development. This will start a Docker container for PostgreSQL, but will use a local copy of tsc, webpack, node, etc so you can iterate quickly.

Once things have started up, you can open http://0.0.0.0:2425/webpack-dev-server/. This will automatically reload on browser changes, and the backend will also automatically restart on server-side changes.

Handy environment variables:

  • NODE_ENV: when unset or development, you'll get full source maps & debug logs
  • DEBUG_SQL: when set (to anything), this will show SQL queries on the terminal as they execute

Testing

npm test will run unit tests. These are primarily server focused.

npm run test-ui will run Selenium tests. You can set the environment variable SELENIUM_DRIVER if you want a custom driver -- by default, it'll try to use Chrome, and if that's not available it'll fall back to PhantomJS.

When debugging UI tests, it may be easier to change standalone-chrome to standalone-chrome-debug in docker-compose.selenium.yml, and then connect to the container via VNC (port 5900, password "secret"). Run the container and your tests separately:

  • docker-compose -f docker-compose.selenium.yml up --build
  • tsc && jasmine --stop-on-failure=true 'build/selenium/*.spec.js'

Tests failing for seemingly no reason? driver.sleep not working? Make sure your Jasmine timeout on your test is high enough.

oss-attribution-builder's People

Contributors

dependabot[bot] avatar hyandell avatar iamwillbar avatar jamesiri avatar jpeddicord avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

oss-attribution-builder's Issues

Issues with large projects

On bigger projects, oss-a-b can be a bit slow since the JSON payload for packages_used is sync'd for each edit. This can result in a sluggish UI and apparent timeouts, resulting in duplicated packages submitted. Then, when removing a duplicate, both packages get removed since they'd have the same package ID. (This doesn't affect multiple revisions of packages, since those would result in new IDs for modifications.)

Migrate off JWTs for sessions

These turned out to be a rather large maintenance pain. More practical to use an existing solution (say, Passport) and cookies instead of trying to manage session data in the browser.

Auto-discover license from URL

For packages with GitHub/Bitbucket/etc URLs, there's a high chance we can automatically discover and import a package's license text.

Fix ACL logic

ACLs currently only use the 'owner' permission level, and even then the support is rather poor. This is an artifact of removing a permission system that was married to Amazon-internal systems, and it now needs some fixing up.

TAGS: transformCopyright() not working as expected with 'notice'

The function transformCopyright() may be provided by TAGS attached to a license to modify the text to be produced for the copyright statement.

For Apache-2.0 license the tag notice is defined which should strip off the copyright notice at the beginning of the attribution text and append it as 'see following NOTICE:' at the end.

This does not seem to work as expected, as the following steps show:

  • Create a new project
  • Define a new package using 'Apache-2.0' license.
  • Build attribution document.

The document generated contains the copyright notice TWICE, one occurence at the beginning of the text and one at the end.

The expected behavior is that the copyright NOTICE only appears ONCE at the end of the text.

Archiving projects

Provide a way to archive a project to hide it from view. Somewhat like deleting a project, but non-destructive.

API for adding components

We've collected information about many components from other sources and would like to be able to add them programmatically. We'd need an API for getting, adding, and updating components.

Figure out Gulp/build situation

Things are broken on Node versions newer than 6.

  • Migrate to Gulp 4?
  • Drop Gulp entirely and use something else? npm scripts, makefiles, etc?

No UI for editing project ACLs

Once a project has been created, it's not possible to edit the ACL, or even the owner, via the UI. The API is (mostly) there.

Marking components as validated/confirmed/curated

We've been considering the ability to mark license/copyright information as having been validated/confirmed/curated if an "approved" person has looked at it (or the information has come from a trusted source).

I'm considering a couple of changes and wanted to get your input on them:

  • Add an attribute to components to flag that the information has been validated (probably a date and some kind of field to track who did the validation)
  • Add a page that lists components and allows them to be edited (specifically to allow marking a component as validated)
  • In the component selector when you're editing a product's attribution provide some kind of indicator against validated components

Tracking issue for Bootstrap conversion issues

The UI was recently migrated from Bootstrap 3 to 4 (alpha 6). Some components may have been missed. Scan through and clean these up -- it's possible for there to be nothing left to do.

Programmatic access

Right now, the attribution builder assumes that a person is using the website. This is reflected in audit logs, access checks, etc. It's possible to implement a custom auth backend that allows for programmatic access, but that gets a little hacky and doesn't play nice with traditional authentication.

To solve issues like #14, I'm thinking of building in support for programmatic clients that access the site via API keys. These keys will map to user accounts and will be stored in a new database table (or perhaps Redis, since it's in the firing line of a request). These could then be configured to access resources via the usual configuration system. API clients could then present an Authorization header with said key.

I'd imagine the format of that table would look something like this:

username api key roles
bot-account-1 oaridgmcfpuydarxst [ add-packages, verify-packages ]

I'm not sure there will be any kind of UI for this; at most there'd be a CLI tool to create an API service user. Still thinking of specifics, but there's a rough overview.

Project contact lists are inflexible

The storage mechanism for contacts is flexible, but the UI currently only allows for one contact to be listed: a legal contact. There's no reason to not allow for arbitrary types, possibly specified via configuration.

Closing down oss-attribution-builder

Due to our own shifting needs we have decided to stop building or supporting oss-attribution-builder. We will be archiving it in place as others might find value in the content and I hope some do.

While this package is no longer being supported you can still hop on over to the TODO Group Slack channel to discuss/discover tooling that is pertinent to this domain.

API: attaching packages seems to mess up packageIds

Thanks for adding this! :) Going through the API I noticed that "attach a package to the project" requires a "packageId" (which apparently can be any number<=total amount of packages in database)
Attaching this new package then returns the actual "packageId" of the new package created in the attribution-builder database.
I don't understand yet, why "packageId" is required at all, and new packages are never checked for duplicates.
Let's say my project already has:
"packageId": "1"
"name": "Pkg1"
"version": "1.0.0"
and
"packageId":"2"
"name":"Pkg2"
"version":"1.0.0"

Attaching
"packageId":"1"
"name":"Pkg2"
"version":"1.0.0"
simply attaches a duplicate of "Pgk2" to my project (which I can't delete via the API) and returns "packageId":"3"

This might be obvious for someone else, but I don't see the reason for this yet.

Include SPDX license texts

At the moment, for text to be available for a license, it has to be manually entered into the licenses/known directory. SPDX publishes texts in a standard manner and it should be easier to use these from within the attribution builder.

API: creating a new project returns "You cannot remove yourself as an owner."

There is another Issue I ran into. When I first used the API to create a new Project, I would use an input structure as follows:
data class NewProject( val title: String, val version: String, val description: String, val plannedRelease: String, val contacts: Contacts, val acl: ACL, val metadata: ObjectNode )

data class ACL( val everyone: String )

This would work perfectly fine, as long as val everyone = "owner"
Now, going through the code again, I changed it to:
enum class ACL(private val permission: String) { OWNER("owner"), EDITOR("editor"), VIEWER("viewer"); @JsonValue override fun toString() = permission }
And the same request returns: "error":"You cannot remove yourself as an owner." for ACL.OWNER

I can't really see, where/ why/ how that happens :(
Weirdly, the same error occurs when I change it back to the first implementation, but replace the value name by anything else but "everyone". For example:

data class ACL( val role: String )

Could anyone ;) clarify this for me?

Project cloning

Being able to clone an existing project for a new version or major release would be useful. Otherwise digging out old attribution documents can be a pain.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.