Tuf: Roadmap for cli tools: repo.py, client.py

[lukpueh]

Description of issue or feature request:
Recently, several issues and some fixes related to the TUF command line tools repo.py and script.py have been brought forward: #873, #874, #876, #877, #878, #879, #880 and "Some comments on TUF..." on the mailinglist. These include concerns about the script names, unexpected behavior, missing TUF features, etc.

@awwad has pointed out that repo.py and client.py are mostly tutorial tools, useful to get familiar with TUF (see QUICKSTART.md). Whereas an actual TUF integration will require direct use of the underlying libraries tuf.repository_tool and tuf.client.updater.

Given the recent GitHub and mailing list activity around these tool, we need to either clarify that these tools are purely for educational purpose, or develop them more actively so that they can actually used by an integrator.

Thanks, @cminyard and @lixuefeng2 for bringing this to our attention!

Current behavior:
The use of and plans for repo.py and client.py are unclear.

Expected behavior:
Decide to what extent repo.py and client.py should be enhanced, maintained, etc.

[trishankatdatadog]

I think we should just remove these old document and code altogether. I think it confuses people more than it does help them. What do others think?

[cminyard]

On Tue, May 28, 2019 at 07:32:34PM +0000, Trishank K Kuppusamy wrote:

I think we should just remove these old document and code altogether. I think it confuses people more than it does help them. What do the others think/

I would disagree strongly.

The client code was useful as a reference. It's not terribly useful on
it's own, but it could be used for some basic testing.

The repo code is useful in a lot of ways:

• The level of abstraction in TUF currently is fairly low. This has a
  couple of bad side effects:

  • Everyone will re-create the same code over and over again.
  • People will get things wrong.
  • People won't use it because it's too hard to use.
    If you have a good level of abstraction, it makes things a lot easier.
    For instance, there is no "add this set of files to the repository as
    this role" function. But that is something that everyone who uses it
    will do. And it really doesn't vary much between users.
    The repo code kind of has that, but it's not exactly intended for
    that purpose.

• As I mentioned before, what people will be doing on the repo side
  won't vary much. It would be nice if all TUF users could have a
  single UI for basic repository functions.

• Users are going to want to wrap things with shell scripts. Not everyone
  want's to dig into python, and it's not necessary when you have a tool
  with a good UI.

• It's useful as example code, of course.

IMHO, the higher level of API abstraction should be split out of the repo
code, cleaned up, and extended. Then a repo tool that is thought through
well should be created on top of it in a way that it can be extended by
others. The current repo interface isn't too bad, but it could be
improved.

I agree that the current situation is not ideal, but I don't think just
deleting the code is the right direction.

-corey

[trishankatdatadog]

@cminyard I don't disagree with you, but I think as a compromise we could move this code and documentation elsewhere. Does that sound agreeable to you?

[cminyard]

On Tue, May 28, 2019 at 02:14:44PM -0700, Trishank K Kuppusamy wrote:

@cminyard I don't disagree with you, but I think as a compromise we could move this code and documentation elsewhere. Does that sound agreeable to you?

I am using the repo code, it means that I will have to basically have to
duplicate it until something comes along that I can use. It's not an
ideal situation, but I'm ok with it.

You could move it down one level into the tuf directory. It could be
used, but not directly as a script. I'm not sure that would accomplish
what you want, though, as it would mean it would become a more formal
part of the API. Yeah, that's probably not a good idea.

BTW, I didn't find it confusing. It's really nice to be able to play with
a repo without having to write any code, just to get a feel of how it's
supposed to work. I was confused that it didn't have a timestamp update
function as an example and thought I was missing something, but that's
about it.

-corey

[lukpueh]

Thanks for chiming in, @trishankatdatadog and @cminyard! Here are my 2 cents.

IMHO, the higher level of API abstraction should be split out of the repo code, cleaned up, and extended. Then a repo tool that is thought through well should be created on top of it in a way that it can be extended by others.

yes! Let's try to identify what parts, currently in repo.py/client.py (or missing from it), should be in repository_lib or repository_tool, and client.updater respectively, e.g. "add this set of files to the repository as this role", etc. (see https://github.com/theupdateframework/tuf/pull/878#pullrequestreview-242216754 for related observations).

...could move this code and documentation elsewhere

yes. The cli script(s) could live in a separate repo, e.g. tuf-cli, along with related documentation. Ideally, all they do is parsing arguments and call into the corresponding library functions (similar to what we do in in-toto/in-toto#in_toto_run.py). I am also happy to reconsider using an alternative to argparse. @trishankatdatadog, you seemed very fond of click?

[trishankatdatadog]

@lukpueh click is awesomeness

[lukpueh]

Consider re-visiting related stale PRs, when addressing this issue:

• "catch the securesystemslib exception add supply advice" #877
• "check if absolute path when add target into repo" #878
• "Added missing docstrings for CLI script functions" #805

Same goes for CLI-related issues:

• "Add CLI to the Repository Management Tools" #270
• "Should trusting/distrusting a key with repo.py bump the version number?" #847
• "Review of the CLI and supporting documentation" #741
• "Mock test CLI and complete docstrings" #763
• "Make the repo script usable from other scripts" #873

[lukpueh]

@Silvanoc kindly provided the following bug reports related to repo.py:

• CLI failure: 'repo.py --sign' fails for RSA (https://github.com/theupdateframework/tuf/issues/998)
• CLI missbehaving: option '--pw' doesn't work for '--sign' (https://github.com/theupdateframework/tuf/issues/999)

[lukpueh]

More issues with the the cli tools, kindly reported by @Jakeler:

• KeyError while trying to delegate to new role with CLI (#1114)

[lukpueh]

Maybe we should add a disclaimer to the cli tool docs that references this collection of issues. And maybe we should create an issue label instead of listing the issues here. :)

[Jakeler]

Let's try to identify what parts, currently in repo.py/client.py (or missing from it), should be in repository_lib or repository_tool, and client.updater respectively, e.g. _"add this set of files to the repository as this role_", etc. (see #878 (review) for related observations).

How is the current state, has someone already looked at this?
Is there anything missing that blocks making repo.py/tuf-cli just a cmdline abstraction around repository_tool?

[lukpueh]

Is there anything missing that blocks making repo.py/tuf-cli just a cmdline abstraction around repository_tool?

Not directly missing, but we are in the process of planning a larger refactor of repository_tool and repository_lib, which should also make it a lot easier to build a command line interface. We will update about the status of the planned work here too.