OSS Discovery FAQ

What does OSS Discovery do?

OSS Discovery is a tool that finds installed open source software. It can be used to inventory open source software across an enterprise or on a single computer. In an upcoming release, OSS Discovery will also enable individuals and companies to easily contribute data to The Open Source Census.

What is The Open Source Census?

The Open Source Census is a global, collaborative project to collect and share quantitative data on the use of open source software in the enterprise. Scan contributors can view summarized results of their scans and benchmark their open source usage against similar organizations.

How do I submit information to The Open Source Census? Will the data gathered be confidential?

OSS Discovery allows you to anonymously contribute the results of your scans to The Open Source Census. For more informationon anonymity and security, plese see the The Open Source Census FAQ.

How does OSS Discovery find open source software?

OSS Discovery scans the file system on a computer looking for open source software and finds open source software by using fingerprints, also called project rules. Project rules uniquely identify open source software using a variety of criteria, including file names, directory structures, file checksums and file contents. Each scan produces a text file with a list of open source software packages and versions found.

Can OSS Discovery scan workstations? Servers? Production systems?

OSS Discovery can scan workstations or servers. It can also scan production systems.

Which open source software can OSS Discovery find?

OSS Discovery can find any open source software package or version for which there is a project rule. OSS Discovery comes with a library of project rules that can identify a wide range of open source software. To see all current fingerprints, go to the List the Fingerprints page.

Community members can contribute new fingerprints by creating project rules for inclusion in the library. The wishlist of project rules we would like to add is in our Roadmap.

You can also extend OSS Discovery to find any software package in your environment by adding custom project rules.

How do I create or contribute a new fingerprint (project rule) to find an open source package?

Available for use as templates are the hundreds of project rules that come standard with OSS Discovery; you'll find them in the discovery2-client/lib/rules directory. You should add your project rules to the discovery2-client/lib/rules/drop-ins directory and give them an .xml extension.

For more detailed technical information describing how to write project rules, see the Developer Guide. See How to Contribute Fingerprints to learn how your new project rules can be included in the OSS Discovery library of rules.

What's next for OSS Discovery?

Please see our Product Roadmap for a glimpse into the future of OSS Discovery.

What license does OSS Discovery use?

OSS Discovery uses the GNU Affero General Public License Version 3 (AGPLv3). Keep in mind that you will also need to install Ruby which has its own licenses

Where will OSS Discovery be installed?

The OSS Discovery archive can be extracted into any directory you choose and does not require any additional "installation" process. There are no libraries or services installed into your operating system directories (/usr/lib, windows system32). Currently, OSS Discovery is supplied in the form of a Ruby script and thus requires Ruby be installed to run.

What if I don't have administrative privileges on my machine, can I still run OSS Discovery?

Yes. The scan will be limited to the files you have permission to access. In the scan report, you will see a count of the number of files or directories to which permission was denied.

Keep in mind that OSS Discovery does not have to scan an entire machine. For example, it can also be configured to scan the home directory of a single user.

What do I need to install and run OSS Discovery?

To run your first scan with OSS Discovery, follow these steps:

1. Download and install Ruby 1.8.5 or 1.8.6 from www.ruby-lang.org.
2. Extract the OSS Discovery archive into your desired [install directory].
3. In a command line or shell, navigate to the [install directory]\discovery2-client directory and run the following command:
   discovery.bat --path [path to directory to be scanned] (if you are running on Windows)
   ./discovery --path [path to directory to be scanned] (if you are on Linux or other UNIX platform such as Solaris)
4. Human readable results get printed to screen.
5. Machine readable results get written to the scan_results.txt file located in the installation directory.

Although you currently need to download and install Ruby prior to running OSS Discovery, in an upcoming release we will deliver this as a combined package.

How do I specify what directories OSS Discovery should ignore during a scan?

You use a filter to specify which directories should not be scanned.

Examples are available in the directory discovery2-client/lib/filters/no-hidden.rb, no-system.rb, no-tmp.rb. See also filters/generic-exclusions.rb.

How can I see what directories have been filtered?

Use the command line option:
--list-filters

Why would I want OSS Discovery to ignore, or exclude, certain directories from a scan?

Some directories – such as the Recycled Bin and many system directories on Linux – will not contain any relevant information not already gained when OSS Discovery detects the operating system. Scanning these directories increases the scan time. Additionally, many of these types of directories may be protected from scanning unless you're the system admin or root user.

Does OSS Discovery follow or not follow symbolic links on Linux or Unix systems?

By default, OSS Discovery will follow symbolic links and automatically detect circular links.

To tell OSS Discovery not to follow symbolic links, use the command line option:
--nofollow

What's the difference between a "filter" and a "project rule"?

A filter is used to exclude files or directories from a scan. These might include system directories, mount points, or other parts of a file system containing undesirable files.

A project rule is used to determine if any given file matches any of the identifying criteria specified for an open source software package. If an open source package's project rule matches a file, that package has been installed.

Where is the configuration file for OSS Discovery?

OSS Discovery ships with a number of standard configurations. These are included in the config.yml file. You will find that file in the discovery2-client/main/lib/conf directory. Developers who've checked out OSS Discovery for development will find it in [checkout dir]/main/lib/conf. For detailed information on configuring OSS Discovery, see the OSS Discovery 2.0 User Guide.

What if I always rename the standard project files on my system? If the filename doesn't match an existing rule, will OSS Discovery find it?

You can add a new 'matchrule tag' that matches your file naming convention to the project rule for that open source package.

I see that OSS Discovery relies on filenames and binary searching techniques, but I can easily hide software from a scan if I rename a .jar or binary file, or if I build it with no version information in it. How does OSS Discovery handle attempts like this to hide projects?

OSS Discovery may not find the open source package in these cases. The goal of OSS Discovery is to find most open source projects in their native form – the form in which they have been distributed from common sources.

Does anybody else get a copy of my scan results?

The results of your scan are private to you. In an upcoming release, OSS Discovery will provide an option for you to contribute anonymous results (with no information that identifies you or your company) to The Open Source Census. Data will only be submitted if you select that option and will be completely anonymous. If you contribute data to The Open Source Census, you will be able to see aggregated summaries of your and other contributors data online. You can then use this data to benchmark your open source usage against other individuals or companies.

Is it safe to run OSS Discovery on a production system?

Right now Discovery has no throttling built in to it, though we plan this for a near term release. There should be no problem running it on a lightly loaded production box, but it may not be advisable to run OSS Discovery on a heavily loaded production machine. If possible, administrators should run it and test for adverse performance affects in a staging environment first.

I expected Package X to be detected, but it wasn't. What are the possible reasons it was missed?

There are several possibilities. First, there may be no project rule written to detect Package X. If the project rule exists, it may be incomplete (doesn't account for a particular version of a file); the regular expression used to match the filename may be incorrect; or the binary match pattern may be incorrect for a given match rule.

If I have multiple versions of the same project installed on my machine, will OSS Discovery find one version only or all of them?

OSS Discovery will attempt to find and report all versions and if all projects lie installed within the subdirectories of the path scanned, then they would be found. For example, if you have one Apache installation in /usr/local/apache2 and one in /opt/httpd-2.0.59 and you do a root (/) level scan, both should be found.

How can I find out the list of patterns OSS Discovery will use to look for files that should be analyzed?

After all filters and rules have been applied to a system, the files that remain are OSS Discovery's 'files of interest'. Use the command line option to list these files that will be included in the scan:
--list-foi

I know I have Package X on this machine and I can see that it should be matching a project rule, but it's not being detected. How can I find out why?

OSS Discovery has several options to help diagnose this. You can see which files are being excluded from the scan and by what exclusion filter by using the --list-excluded option. Additionally, you can view the files which will be included in a scan by using the --list-files option.

OSS Discovery reports that I have Package X installed, but I don't.

A fundamental principle of OSS Discovery is that it presumes there will be at least one file that uniquely identifies an open source package on the machine if that project is installed. If that one file has a filename that's a duplicate of a file name in any other project, it's theoretically possible to get a false positive like this. We would consider this a rule conflict and would consider modifying the rule to change the key file used to base the rule. Please report this in the OSS Discovery bug tracker so we can review the issue. Alternatively, if you have determined what the fix is, you can also submit a rule fix through the OSS Discovery web site.

OSS Discovery reports that I have open source packages installed that I don't know anything about. How do I find out more?

Information on over 130,000 open source packages is freely available on OpenLogic Exchange (OLEX).

How were these projects I don't recognize installed? How do I figure out what is using them?

Often packages will be detected because they come bundled as support software for another program you installed. For example, if you have Jboss or Ant installed, it's likely you have other open source packages installed as bundled support for those programs. Usually, the paths or location of the bundled package is the Ant or Jboss installation directory, for example.

If you'd like, you can run OSS Discovery before installing an open source package, make a backup copy of the scan results file, install the new package, then re-run OSS Discovery. If you had a whole stack of software to install and you really wanted to see what package added which bundled projects, you could run OSS Discovery between each package installation.

How do I remove open source packages I don't want?

Approach the removal like you would the uninstallation of any type of software. Keep in mind that the files may be used by other elements of your system.

Can I run OSS Discovery on multiple machines?

Yes. OSS Discovery is released under an open source license, so there are no license restrictions on how many machines you can scan. In fact, to get an accurate inventory of open source used in a company or enterprise, you will need to run it on multiple machines.

How do I run OSS Discovery on multiple machines in a company?

The easiest way to run OSS Discovery on multiple machines is using your existing software distribution tools. Keep in mind that until OSS Discovery is packaged with a platform-specific or platform-independent implementation of Ruby, Ruby will need to be part of the package the distribution tool pushes.

How can I tell which machine in a production environment produced which scan results?

Each scan_results.txt file contains a machine ID in its results. You can use this to track individual scans. However, because it's an 32 character MD5 checksum, it's a one-way hash and can't be used by anyone to identify the hostname or IP address of a machine.

What operating systems can I run OSS Discovery on?

We've tested OSS Discovery, and support it on the following platforms:
Windows XP, 2000, 2003
Solaris 8, 9, and 10 (SPARC)
SLES 9 and 10 Linux
RedHat Enterprise 3, 4, 5

It's also known to run on many other platforms which support Ruby.

Can OSS Discovery tell me what operating system (Linux distro) it's running on? How can I get that information from Discovery?

Use the following command:
./discovery --list-os (if you are on Linux or other UNIX platform such as Solaris)
discovery.bat --list-os (on Windows platform)

When will my platform be supported?

Since OSS Discovery is written in Ruby, it relies on a Ruby port to the platform you're using. If Ruby is running on your platform, there's a good chance with little or no modification that OSS Discovery will run. We could always use more help from people who would like to maintain ports of OSS Discovery to platforms other than those currently supported so joint the community if you're interested.

Will OSS Discovery detect an open source Windows binary on a Linux file system?

Yes, and vica versa, assuming the project rule is written correctly. The way OSS Discovery scans and detects files is platform independent. So, it's possible for OSS Discovery to find an apache.exe file and a linux apache httpd file on the same file system. The project rule must account for the correct filenames on either platform.

What does the contributor agreement do?

The OSS Discovery Contributor Agreement gives OpenLogic and the contributor joint copyright interests in the code contributed to OSS Discovery. The contributor keeps the copyrights to their code while also granting those same rights to OpenLogic, the OSS Discovery sponsor. The contributor agreement also gives OSS Discovery and OpenLogic a license to any patent rights owned by the Contributor that are used in the contribution. OSS Discovery is licensed under the GNU Affero Public License - the contributor agreement does not change the rights or responsibilities of the OSS Discovery project under the GNU Affero Public License.

Who has to sign the contributor agreement?

Anyone who intends to contribute source code, design documentation or documentation to OSS Discovery, regardless of the size of the contribution, should sign the contributor agreement. All contributors to OSS Discovery should sign the contributor agreement, as it makes it easier to keep track of contributions.

Why does OSS Discovery have a contributor agreement?

OpenLogic asks that you share the copyright on your contributions so OpenLogic can protect the contents of the OSS Discovery project. By agreeing to the contributor agreement, contributors protect the OSS Discovery code base, enable alternative licensing models, and protect the flexibility to adapt the project to the changing demands of the community.

Who should sign the contributor agreement, me or my company?

If you are contributing changes on behalf of your company, an executive representative of the company must sign the contributor agreement and indicate his/her title. If the company wants to, it can add a list of employees as an attachment to the contributor agreement.

Once I have signed the contributor agreement, can I change my mind?

You may stop participating in OSS Discovery whenever you want to but the contributor agreement will remain in place for any and all contributions you have already made.

I submitted code to OSS Discovery but my code wasn't accepted. Does the contributor agreement still apply to it?

The OSS Discovery contributor agreement still applies to your contributions even if they were not incorporated into the main project. Of course you may continue to exercise your copyrights and you can contribute the code to another project if you want to.

Why does the contributor agreement have a patent clause?

OpenLogic wants to make sure that none of the contributors is holding a patent that would prevent someone from being able to use OSS Discovery. OpenLogic does not plan to use a contributor's patent license beyond what is reasonably necessary to fulfill the goals of OSS Discovery.

How do I sign the contributor agreement?

See instructions on the OSS Discovery Contributor Agreement.