Metadata-Version: 2.4
Name: fluidattacks-agent
Version: 0.5.0
Summary: In-process probe reporting what a Python workload imports and runs
Project-URL: Homepage, https://fluidattacks.com
Project-URL: Source, https://gitlab.com/fluidattacks/universe/-/tree/trunk/watches/agents/python
Author-email: Development <development@fluidattacks.com>
License: MPL-2.0
Keywords: dependencies,observability,reachability,runtime,sbom
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# fluidattacks-agent

Reports what a running Python workload actually imports and runs, so that a
dependency inventory can say which of its findings are reachable at runtime and
which are not.

It is a library, not a service. It observes the interpreter it is installed in,
sends what it saw, and does nothing else. It takes no dependencies: the
standard library only, because it is installed into workloads we do not own.

## Installing

```
pip install fluidattacks-agent
```

That is the whole setup. A `.pth` file at the root of the wheel starts the probe
at interpreter start, before the workload's own program runs, so nothing has to
be imported or called by hand.

## Turning it off

```
FLUIDATTACKS_AGENT=off
```

Also `0`, `false`, `no`, `disabled` or `none`. A workload that says no pays for
reading the setting and for nothing above it. Saying nothing is taken for yes,
because installing the package is the consent.

## What it observes

- distributions whose modules were imported, and which modules
- functions that were executed, where the interpreter offers that
- how often, in windows, and when a symbol was first reached

Only what an installed distribution owns is attributed. The standard library and
a workload's own first-party code produce no records.

## The credential

Naming a credential is what makes the probe observe at all. A workload that
names none starts nothing:

| | |
|---|---|
| `FLUIDATTACKS_AGENT_TOKEN_FILE` | a file holding the credential, preferred |
| `FLUIDATTACKS_AGENT_TOKEN` | the credential itself, read only if no file is named |
| `FLUIDATTACKS_AGENT_WORKLOAD` | what this workload is called, optional |

A file is preferred over a variable because a file can be mode 400, while an
environment variable is readable by any process of the same user.

The credential is issued for one root of the platform and names it: reports
are filed under that root and nothing has to say which. Where reports go is
fixed in the probe; no setting names an address. A credential of any other
shape is a misconfiguration, and the probe starts nothing rather than sign
what nobody could file.

## What travels, and what does not

Reports are gzipped and signed with a key derived from the credential; the
credential itself never travels, appears in no record, and is in no exception.
The far end must prove who it is — certificate chain and hostname both — and no
redirect is followed.

What a report contains is distribution names, versions, module and function
names, and counts. No arguments, no return values, no file contents, no
environment.

## Licence

MPL-2.0
