Metadata-Version: 2.5
Name: fluidattacks-agent
Version: 0.3.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.

## Where reports go

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

| | |
|---|---|
| `FLUIDATTACKS_AGENT_ENDPOINT` | where reports are posted, `https://` only |
| `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_GROUP` | what the reports are filed under |
| `FLUIDATTACKS_AGENT_WORKLOAD` | what this workload is called |

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.

An endpoint named without enough beside it to reach — no credential, or not
`https://` — is a misconfiguration, and the probe starts nothing rather than
observe what it could never deliver.

## 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
